15:31:28 <acozine> #startmeeting Ansible Documentation Working Group 15:31:28 <zodbot> Meeting started Tue Apr 2 15:31:28 2019 UTC. 15:31:28 <zodbot> This meeting is logged and archived in a public location. 15:31:28 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:31:28 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:31:28 <zodbot> The meeting name has been set to 'ansible_documentation_working_group' 15:31:50 <acozine> #chair samccann bcoca felixfontein 15:31:50 <zodbot> Current chairs: acozine bcoca felixfontein samccann 15:31:54 <acozine> who else is around? 15:32:17 <kmaxwell> I'm here 15:32:42 * gundalow waves 15:32:53 <acozine> #chair kmaxwell gundalow 15:32:53 <zodbot> Current chairs: acozine bcoca felixfontein gundalow kmaxwell samccann 15:33:00 <acozine> kmaxwell: welcome 15:33:08 <acozine> I see you've added an item to the agenda 15:33:21 <acozine> #topic https://github.com/ansible/ansible/pull/50958 15:33:38 <kmaxwell> Thanks acozine, hope you haven't been fighting just as much ice as last time I made it! 15:33:44 <felixfontein> sorry, I'm not really here, I just have to fix a bug before the ZH meetup starts :) 15:34:04 <acozine> felixfontein: squash those bus 15:34:07 <acozine> er, bugs 15:34:28 <acozine> how do I remove someone from the chairs list? 15:34:39 <acozine> kmaxwell: we're having "spring" here in the midwest US 15:35:12 <gundalow> #unchair felixfontein 15:35:12 <zodbot> Current chairs: acozine bcoca gundalow kmaxwell samccann 15:35:24 <acozine> which means temperatures hopping above and below freezing and a bumper crop of potholes 15:35:43 * bcoca is actually on bench 15:36:21 <acozine> less indoor ice, though, if you're remembering the "ice palace" incident from a few months ago 15:36:31 <acozine> #unchair bcoca 15:36:31 <zodbot> Current chairs: acozine gundalow kmaxwell samccann 15:36:36 <acozine> right, small group today 15:36:37 <samccann> that's progress! 15:36:50 <kmaxwell> Yes! that was quite a memorable set of photos 15:37:06 <kmaxwell> That topic was one I suggested, a vault PR that looks good 15:37:32 <acozine> I seem to remember we have some stale vault PRs as well 15:37:39 <acozine> shall we look at them somewhat together? 15:37:53 <kmaxwell> s/vault PR/vault docs PR/ 15:38:02 <acozine> heh, good reminder 15:38:09 <kmaxwell> sure happy to, that one look great for me, I check the behaviour matches 2.7 15:38:22 <acozine> ah, awesome, thanks for testing the docs! 15:39:38 <acozine> I'm not an expert on vault - do we version vault separately from Ansible? 15:39:52 <kmaxwell> Don' think so 15:40:00 <acozine> I'm curious about https://github.com/ansible/ansible/pull/50958/files#diff-08769c7d5e370703d8175ddb1822d81eR373 15:40:29 <samccann> I thought that referred to some format. so the format is version 1.2 15:40:39 <samccann> I've seen something similar I think in other Vault docs 15:40:49 <kmaxwell> Yeah basically if you use an ID then the format is 1.2, otherwise 1.1 15:40:56 <acozine> ah, I thought they might be references to a local machine's available vault values 15:41:00 <gundalow> If `(with format version 1.2)` means Ansible 1.2, then no need to mention that 15:41:00 <acozine> good to know 15:41:01 <kmaxwell> 1.0 is an old format that is upgraded automatically 15:41:22 <gundalow> oh, no, how old is vault 1.1? 15:41:24 <gundalow> or 1.2? 15:41:29 <kmaxwell> No sorry that was unclear, I mean vault file format version 1.2 not ansible version 1.2 15:41:46 <acozine> so this is broadly similar to the metadata versions - something that we manage without reference to the main Ansible version numbers 15:42:35 <acozine> heh, this PR didn't introduce or change this, but my eye is drawn to the word `hexlifyied` 15:42:43 <kmaxwell> Yes worry I am causing confusion, ansible-vault is released as a part of the main ansible release, currently 2.7 15:43:13 <kmaxwell> Its on disk file format has gone through three version I'm aware of 1.0, 1.1 and 1.2 15:43:36 <kmaxwell> Ansilbe 2.7 writes 1.2 vault file format if you use an ID, 1.1 if you don't 15:44:24 <acozine> gotcha 15:44:25 <samccann> bit of an aside, but we don't document what format 1.2 is... we do have a section for 1.1 - https://docs.ansible.com/ansible/devel/user_guide/vault.html#vault-format 15:44:49 <acozine> samccann: that's the part this PR updates 15:44:57 <samccann> and I think `hexlifyied` is referring to the python hexlify() but that's just a guess 15:45:13 <acozine> that makes sense 15:45:15 <samccann> (and not saying it's the right way to go about that description :-) 15:45:35 <acozine> we could make that a link to the python docs 15:45:45 <acozine> but we don't need to make this PR do that work 15:45:54 <samccann> doh! thanks @acozine - got so caught up in what that version number meant, I didn't read the pr! 15:46:28 <acozine> hm, and searching the docs PRs, I don't see other vault-related ones currently 15:46:49 <acozine> I think we can merge 50958 15:47:13 <samccann> +1 for merge 15:47:20 <acozine> gundalow: any thoughts? 15:47:27 <kmaxwell> I agree on 50958, if you'd like a separate PR to link hexlify I can do that, is https://docs.python.org/3/library/binascii.html#binascii.hexlify the right destination? 15:47:44 <acozine> kmaxwell: yes, that's the right link 15:47:46 * gundalow doesn't know much about vault. Though I think the PR is an improvement 15:48:03 <acozine> we are unanimous, then - I'll mark the PR rebuild_merge 15:49:27 <acozine> kmaxwell: I think there's a special shortcut syntax for links to the python docs, let me see if I can remember or dig up details 15:49:53 <kmaxwell> Awesome! I had a look at short list from the log from last time I brought up vault at this meeting, any you're right that's the last one 15:51:14 <samccann> should we backport that PR as well once it merges, to get this info into 2.7? 15:51:23 <kmaxwell> acozine: is that something then project generally likes? Links to the Python docs? 15:52:30 <acozine> kmaxwell: if the docs mention a standard library, linking to the docs from that mention is useful 15:53:19 <samccann> is that cross linking what is described here ? - http://www.sphinx-doc.org/es/stable/ext/intersphinx.html 15:53:28 <acozine> samccann: yes, that's it 15:53:53 <kmaxwell> the docs for a couple of wrappers around python functions, would IMO really benefit from links, I will try to remember details and submit a PR 15:54:03 <acozine> kmaxwell: awesome! 15:55:32 <acozine> #topic Scenario Guides update 15:56:00 <acozine> I'm planning to set up the necessary redirects this week, then merge those and https://github.com/ansible/ansible/pull/54554 15:56:02 <bcoca> problem with links ... we have verisoned site and we dont normally fix links in code comments when things move 15:56:32 <acozine> bcoca: can you give me an example? 15:57:13 <bcoca> not top of my head, but a couple of them have been reported 15:57:28 <acozine> bcoca: is this related to the Python links we were discussing, or to the Scenario Guides topic? 15:57:31 <bcoca> i do know we have not had process to fix links in code, nothing that scans them 15:57:42 <bcoca> 'all links in codebase' 15:57:56 <bcoca> aside those in docs, which we normaly use relative constructs for 15:58:29 <acozine> yeah, the python links are relative - if they need updating, we can manage that in one place 15:58:39 <acozine> if that's what you're concerned about 15:59:56 <bcoca> my concern is not currently big, it will be bigger once we start adding 'api docs' from those comments inline of the code 16:00:05 <acozine> they're set in https://github.com/ansible/ansible/blob/18bf48cec2c92e42d0d902be4ce2a49f65247b97/docs/docsite/rst/conf.py#L240 16:00:59 <acozine> I think there are tools that scan and test links in docs 16:01:03 <acozine> we can look into those 16:01:32 <samccann> is the issue broken links or 'old' links - as in the link still works, but it points to some wrong version of 'something' somewhere else? 16:02:34 <acozine> bcoca: ^^^ 16:03:42 <acozine> well, if it becomes an issue, I'm sure we'll hear more about it 16:03:49 <samccann> :-) 16:04:21 <gundalow> As long as links from `/devel/` and `/latest/` to github are correct I'm happy 16:04:38 <bcoca> oh, it should be easy to do/add tools, just pointing out we dont (afaik) currently do 16:05:18 <acozine> well, "stale" links that point to the wrong version of external information are harder to detect than actual broken links 16:05:50 <acozine> fortunately, we have an engaged community, so I trust that people will let us know! 16:07:26 <acozine> any comments on the Scenario Guide thing? 16:07:38 <samccann> LGTM 16:07:55 <samccann> what was it waiting on besides the redirects? 16:08:15 <acozine> just community input 16:08:15 <kmaxwell> Sorry I'm only guessing what bcoca's concern could be about: https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/doc.py#L595 16:08:50 <gundalow> acozine: samccann is it OK to merge scenarios guides to `devel`, then add redirects, then cherrypick to `stable-2.7` 16:09:18 <kmaxwell> For example would that mean that released versions e.g. 2.8 point to latest when it would be even better if they pointed to 2.8? 16:09:22 <gundalow> 2) Do you want to have the redirects PR ready (and reviews) before mergeing 54554? 16:09:29 <bcoca> kmaxwell: that is just one case and its already wrong (should not be latest, but match current version) 16:09:33 <acozine> gundalow: I'd like to get the redirects ready 16:09:44 <acozine> b/c we can't merge those ourselves 16:10:07 * acozine reads that doc.py section 16:10:12 <kmaxwell> bcoca: cool, I agree 16:11:10 <bcoca> acozine: ansible 2.5 docs will point to 2.7 now 16:11:16 <bcoca> and 2.8 soon enough 16:11:39 <acozine> bcoca: you mean from that See Also section? 16:11:41 <bcoca> while the modules 'user has' might not match 'latest' docs 16:11:58 <acozine> we didn't backport that beyond 2.7, so we're okay for now, but you're right that it will become an issue in future 16:12:13 <bcoca> yeah, was just using example 16:12:20 <bcoca> we do have 'ansible version' variable 16:12:51 <acozine> okay, let me write up an issue while I've got the details in my head 16:12:52 <bcoca> though we might need subseet as it is 3 secions 2.7.18 16:18:28 <acozine> bcoca: I put what I know so far into https://github.com/ansible/ansible/issues/54736 16:18:49 <acozine> #topic open floor 16:19:07 <acozine> anybody have other stuff to review, discuss, complain about? 16:19:17 <bcoca> my back hurts 16:19:26 <bcoca> ah .. relating to docs .. nope 16:19:43 <samccann> nothing here 16:20:49 <kmaxwell> Sorry hope I'm not slowing things down - is get_versioned_doclink from plugin_docs.py the right approach to acozine's latest issue? 16:21:11 <acozine> kmaxwell: questions are good 16:21:26 <acozine> but I don't have a good answer for you 16:21:46 <acozine> I would have guessed replacing `latest` with a variable, but maybe there's a better solution 16:22:26 <kmaxwell> maybe that a question at bcoca? get_versioned_doclink from plugin_docs.py acceptable approach? 16:23:30 <bcoca> possibly, dont know the function 16:24:12 <acozine> kmaxwell: if you create a PR, I can build it to the test site and we can try it out 16:24:26 <bcoca> ah, looking at wrong plugin_docs (parsing, its the one in utils) 16:24:31 <gundalow> Nothing else from me 16:25:52 <kmaxwell> bcoca: maybe a link would have been more helpful https://github.com/ansible/ansible/blame/devel/lib/ansible/utils/plugin_docs.py#L114 16:26:15 <bcoca> i found it, i prefer looking at code in vim anywyas :-) 16:26:33 <kmaxwell> I think its only a month old, and isn't widely used which is why I wanted to check 16:26:41 <bcoca> i just forget we have x2 plugin_docs.py 16:27:04 <acozine> huh, I don't think we actually publish docs at that level of granularity 16:27:47 <acozine> the docs at `docs.ansible.com/ansible/2.6/`are the most recent 2.6.x release, generally speaking 16:28:15 <acozine> we don't have `docs.ansible.com/ansible/2.6.2` and `docs.ansible.com/ansible/2.6.3` and so on 16:30:03 <acozine> kmaxwell: are you willing to do some work on 54736 and report back next week? 16:31:50 <kmaxwell> acozine: sorry mean to come back to your earlier offer, yes! :-) 16:31:58 <acozine> awesome, thanks! 16:32:04 <acozine> that's it for this week 16:32:23 <acozine> tune in next week for the next exciting installment of Ansible Docs In Space! 16:32:32 <acozine> I mean, the Docs Working Group . . . 16:32:41 <acozine> thanks everybody! 16:32:46 <acozine> #endmeeting