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