15:01:46 <acozine> #startmeeting Ansible Docs Working Group aka DaWGs
15:01:46 <zodbot> Meeting started Tue May 14 15:01:46 2019 UTC.
15:01:46 <zodbot> This meeting is logged and archived in a public location.
15:01:46 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:46 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:46 <zodbot> The meeting name has been set to 'ansible_docs_working_group_aka_dawgs'
15:01:59 <acozine> #chair samccann
15:01:59 <zodbot> Current chairs: acozine samccann
15:02:06 <acozine> who else is around?
15:02:09 <acozine> #chair kmaxwell
15:02:09 <zodbot> Current chairs: acozine kmaxwell samccann
15:03:26 <acozine> felixfontein: dag decentral1se Pilou shaps Xaroth zoredache alongcha_ andersson007_ are you folks running with the Ansible DaWGs today?
15:03:41 <alongcha_> Not today unfortunately
15:04:08 <acozine> alongcha_: okay, hope to see you next time!
15:05:48 <acozine> I'll start with a reminder:
15:06:00 <acozine> AnsibleFest Call for Proposals closes on May 28th
15:06:02 <acozine> https://ansiblefest2019.eventpoint.com/cfp
15:06:15 <acozine> if you submit a talk proposal and it's accepted, you get free registration
15:06:27 <acozine> we will also be having a Contributor Summit on the Monday of Fest week
15:07:07 <acozine> it would be great to see a lot of documentation champions in Atlanta
15:07:14 <acozine> I hope everyone on this list can come!
15:07:24 <samccann> \o/
15:07:27 <acozine> #topic AnsibleFest details
15:07:43 <samccann> #link https://ansiblefest2019.eventpoint.com/cfp
15:07:58 <acozine> DEADLINE: May 28
15:08:05 <samccann> #info AnsibleFest Call for  Proposals closes May 28th
15:08:10 <acozine> thanks samccann
15:08:22 <samccann> sometimes I remember irc commands!
15:08:31 <kmaxwell> have you a link to last year's talks handy?
15:08:32 <acozine> more often than I do, apparently
15:09:03 <kmaxwell> for inspiration :) or to judge the level
15:09:20 <acozine> kmaxwell: good question - I found some videos here: https://www.ansible.com/resources/videos/ansiblefest-austin-2018
15:10:44 <kmaxwell> ty! I remember watching some of those
15:10:48 <samccann> #link https://www.ansible.com/resources/videos/ansiblefest-austin-2018 to get inspiration from last year's event
15:10:50 <acozine> and here's a blog post from Jeff Geerling about the Contributor summit: https://www.jeffgeerling.com/blog/2018/things-i-learned-ansiblefest-austin-2018-contributors-summit
15:11:13 <samccann> #link https://www.jeffgeerling.com/blog/2018/things-i-learned-ansiblefest-austin-2018-contributors-summit for details on the Contributor Summit that same week
15:11:24 * samccann on a link roll today!
15:11:44 * samccann tho prefers sushi rolls
15:12:14 * acozine is getting hungry now, and lunch is still hours away
15:13:08 <acozine> last year's schedule seems to have disappeared into the Internet of the Past - all the links i can find point to the 2019 CfP
15:13:57 <acozine> #topic PR review and stats
15:14:58 <acozine> in a conversation with dag yesterday, I discovered that some PRs that update the module docs have the label `docs` . . . we are working hard to review all documentation-related PRs and merge as many as we can
15:15:37 <acozine> so if you see a PR that is docs-related, and it doesn't have the `docs` label, add it if you can, or post a link here in the #ansible-docs channel
15:15:46 <acozine> or bring it to this meeting for consideration/review
15:16:08 <acozine> grrr. . . edit fail
15:16:23 <acozine> Some PRs that update the module docs DO NOT have the label `docs`
15:16:34 <acozine> so keep an eye out for those
15:16:41 <samccann> #info not all docs PRs have the docs label if it's module docs.  If you see any, add the docs label or post a link here in #ansible-docs channel
15:16:59 <samccann> speaking of stats, we are down to 61 open PRs for docs!
15:17:21 <acozine> hooray! though with ^^^ it may be a few more than that
15:17:51 <acozine> #topic The Version-Changer
15:17:59 <acozine> take it away, samccann !
15:18:30 <samccann> woo hoo!  So I finally have a version changer mostly working.  You can see it 'in action' on the test site - http://docs.testing.ansible.com/ansible/latest/index.html
15:19:25 <samccann> keep in mind that when you go 'back' a version, you may hit a 404 if the page didn't exist in that release.  also, there are some older version changer hacks on the older test sites (devel, 2.6) that you may see.
15:19:55 <samccann> Once we merge this, we'll have to do a fast backport to 2.8, 2.7, 2.6 to get them all working together so to speak
15:20:08 <samccann> WIP pr is https://github.com/ansible/ansible/pull/55655/files
15:20:17 <acozine> it looks great samccann
15:20:30 <acozine> up in the top section, right where you'd expect to find it
15:20:32 <samccann> (ignore the version.html changes - an older fix I have to back out of the PR now that I have it working at the top of the left-hand navigation)
15:20:50 <kmaxwell> I like it!
15:21:02 <samccann> and I'd love  reviews on the WIP PR - my javascript/html knowledge is straight from Prof. Google
15:21:43 <kmaxwell> (struggling not to mention that somehow latest says devel just above the box, that's maybe something else)
15:21:55 <samccann> yeah that's worth reminding me of for sure!
15:22:11 <samccann> I 'think' it has to do with how I published to the test site, but I need to verify that
15:23:00 <samccann> #info version-changer PR is https://github.com/ansible/ansible/pull/55655/files and needs reviews. Ignore version.html as that needs to be removed from the PR
15:23:23 <samccann> #info - also - determine why the test site shows devel as the version when it is 2.7
15:23:31 <samccann> just so I don't lose that thought!
15:23:49 <acozine> kmaxwell: don't struggle - all comments and observations are welcome
15:24:10 <kmaxwell> better if I just asked what stage are you at? I like the direction you're going
15:24:42 <kmaxwell> happy to try some detailed testing whenever you're ready
15:24:45 <samccann> I need to clean up the PR.  Then do a 'dummy' backport to older versions to make sure the back n forth work
15:24:53 <acozine> so https://github.com/ansible/ansible/pull/55655/files#diff-0b7e420875907c4ef7d35eac6fa3e2deR247 will eventually need to read `2.6 2.7 latest devel`, right? after 2.8 is released?
15:25:02 <samccann> that would be great!
15:25:23 <kmaxwell> samcann: have you decided how to handle pages that don't exist in ealier versions?
15:25:32 <samccann> #info versions need to be 2.6 2.7 latest devel to catch up with the upcoming 2.8 release
15:25:37 <samccann> yep, need to fix that as well
15:25:42 <acozine> I think the `devel` next to latest is coming from https://github.com/ansible/ansible/pull/55655/files#diff-46b6ec95f1914057dc059bd9e2ea6f7bR158
15:26:00 <kmaxwell> the example I stumbled into is http://docs.testing.ansible.com/ansible/2.6/scenario_guides/cloud_guides.html
15:26:10 <acozine> oh, or maybe that's from the Jenkins job . . .
15:26:45 <kmaxwell> maybe for the first implementation of the version changer you don't need fancy handling
15:27:18 <acozine> at an earlier meeting we agreed that having a better 404 page is a pre-requisite for the version-changer
15:27:28 <acozine> there's an issue for it: https://github.com/ansible/ansible/issues/51439
15:27:43 <kmaxwell> I thought I remembered as much, glad you're on top of it
15:27:55 <acozine> any chance you'd like to pick that one up kmaxwell ?
15:29:01 <kmaxwell> just having a read of it now
15:29:59 <kmaxwell> will come back to your question, if we you'd let me just flesh out my understanding a bit more
15:30:30 <kmaxwell> so we add a custom 404 to devel as per issue description
15:30:42 <kmaxwell> which means devel / 2.9 will have custom 404s
15:31:04 <kmaxwell> does that docsite change then get backported to 2.6 2.7 2.8?
15:31:22 <acozine> I'd like to backport both the version-changer and the custom-404  to all supported versions
15:31:47 <acozine> preferably the 404 would be "version-aware"
15:32:11 <acozine> so if you hit a missing page on the 2.6 docs, it would give you links to the 2.6 index page, or section index, or something
15:32:56 <acozine> once 2.8 is released (this week), the supported versions will be 2.6, 2.7, 2.8, and the devel branch
15:33:08 <kmaxwell> I think I was reading today that support is 3 versions / c. 12 months
15:33:26 <acozine> yes
15:33:27 <kmaxwell> you beat me to that ^^^ :-)
15:33:37 <acozine> Ansible 2.5 was released about 18 months ago
15:33:40 <acozine> heh
15:34:41 <kmaxwell> I will comment on the issue to add some of this detail, and if I can make the time try an implementation
15:34:51 <acozine> I think all those stable branches have docs infrastructure that's recent enough that we could backport a custom 404 and the version-changer, though the proof is in the eating, as they way
15:34:57 <acozine> s/way/say/g
15:35:05 <acozine> kmaxwell: awesome, thank you!
15:35:10 <acozine> be sure to note https://github.com/ansible/ansible/issues/51439#issuecomment-481331515
15:35:14 <acozine> ;)
15:35:24 <kmaxwell> acozine: to answer your question in a pretty non-commital way :-)
15:35:33 <acozine> hey, you're a volunteer
15:36:07 <acozine> I don't even get to volun-tell staff, let alone community folks
15:36:11 <samccann> kmaxwell: just add anything you learn/think of along the way to the 404 issue. that way someone else can pick it up if you don't get the chance
15:36:22 <kmaxwell> is the version changer going to block on the custom 404?
15:36:30 <acozine> nope, it's the other way around
15:36:41 * acozine re-reads that
15:36:55 <acozine> yes, the version changer is blocked by the custom 404
15:37:06 <kmaxwell> 404 has to come first is another way of saying the same thing
15:37:07 <acozine> we already have a bad UX with missing pages
15:37:13 <acozine> let's not make it more visible
15:37:21 <acozine> or higher-traffic
15:37:40 <acozine> kmaxwell: yeah, I'm just hopped up on adrenaline and caffeine
15:37:45 <acozine> it's release week!!!
15:38:06 <kmaxwell> :-)
15:38:11 <acozine> skim everything and leap to conclusions!
15:39:04 <acozine> samccann: the version-changer is looking awesome, thank you for all your hard work on it
15:39:16 <acozine> that Prof. Google, she's a pretty good teacher
15:39:39 * bcoca dances with versions
15:39:40 <samccann> heh
15:40:01 <bcoca> does it redirect you to 'upgrade now' page when selecting 1.9?
15:40:13 <acozine> bcoca: heh
15:40:43 <acozine> it should redirect to a very special cowsay picture in that case
15:40:49 <acozine> with a large . . . pile
15:40:54 <bcoca> +1000K
15:41:14 <acozine> #topic open floor
15:42:13 <acozine> I thought dag and Pilou would be here today and we'd have a full review of https://github.com/ansible/ansible/pull/45805
15:42:29 <acozine> maybe next week . . .
15:42:37 <acozine> anyone have other stuff to bring up?
15:42:41 <acozine> PRs to review?
15:42:49 <acozine> Issues to highlight?
15:43:04 <dag> acozine: I am here
15:43:15 <acozine> #chair dag
15:43:15 <zodbot> Current chairs: acozine dag kmaxwell samccann
15:43:23 <acozine> dag: you've been very, very quiet
15:44:07 <acozine> do you want to give a short summary of the arg_spec-to-module-docs PR?
15:45:15 <dag> acozine: I have been very, very busy ;-)
15:45:37 <dag> well, that PR was not finished because it would not be accepted
15:45:45 <acozine> ah, okay
15:46:19 <dag> because some hidden roadmap had foreseen changes to this area 2 versions later
15:46:59 <acozine> hm
15:47:02 <dag> Maybe you know more about this ?
15:47:33 <acozine> maybe? it's not immediately springing to mind
15:47:44 <dag> since then I know there had been internal discussions whether the arg_spec needed to be (completely?) in documentation, or documentation needed (completely?) in the arg_spec
15:47:55 <bcoca> dag: that discussion never ends ...
15:48:02 <bcoca> has been 'vaporware' since 2.1
15:48:02 <dag> bcoca: ok :-)
15:48:20 <acozine> I don't think we can have really good documentation that lives entirely in the argspec
15:48:24 <bcoca> why i just did plugin config ... and ran
15:48:25 <dag> right, but I was told this would never be accepted because of that
15:48:39 <dag> acozine: agreed
15:48:51 <bcoca> acozine: why plugin config uses the docs
15:48:57 <dag> acozine: that's why I still think my approach is best, even if we move something around later something like this will be needed
15:49:04 <acozine> so my concerns are more about how to integrate the parts that *are* in the argspec with the parts that are not
15:49:45 <acozine> right now we make it easy for people to correct mistakes in the documentation, and I want to preserve that ease-of-use
15:49:59 <samccann> tangentially related - the network team has used a 'resource model' that will autogenerate both  the documentation and the arg_spec
15:50:06 <acozine> we may be able to adopt dag's change *and* preserve the ease-of-use
15:52:04 <bcoca> acozine: basically required/default/type become 'programing' while description and rest stay 'pure docs'
15:52:12 <bcoca> ^ choices also
15:52:20 <acozine> dag: do you have time to get the PR updated (passing CI) so we can have a full discussion about it at a WG meeting next week or the week after?
15:52:54 <bcoca> acozine: but it would not only be docs issue, that really affects core more than anything
15:53:21 <acozine> bcoca: what do you mean?
15:53:37 <bcoca> it changes how modules are 'programmed'
15:54:20 <acozine> it does? I thought it pulled existing information from the argspec to produce parts of the documentation
15:54:43 <acozine> bcoca: so what would be the right venue/group for reviewing the PR, then?
15:55:02 <bcoca> but it makes a decision on how the programming is supposed to work
15:55:07 <bcoca> core meeting
15:55:33 <acozine> okay
15:55:55 <acozine> I don't habitually go to the core meetings, but I'd like to be there for this one
15:57:15 <acozine> bcoca: so would dag's PR require changes to most (or all) of the existing modules?
15:57:47 <bcoca> iirc all
15:58:06 <Pilou> (logs of core meeting where this PR was discussed: https://meetbot.fedoraproject.org/ansible-meeting/2019-03-19/ansible_core_irc_public_meeting.2019-03-19-19.05.log.html#l-137)
15:58:11 <bcoca> since you are moving the docs from the 'inline yaml' into argspec
15:58:36 <acozine> it doesn't let us override what's there as an interim step?
15:58:46 <acozine> Pilou: thanks for the link
15:59:05 <bcoca> i forget, have not looked at that in months
15:59:22 <bcoca> `19:40:56 <bcoca> +1 to intent, but -1 to implementation`
15:59:33 <bcoca> ^ i would probably stand with that again
15:59:35 <acozine> well, we're not going to make much progress in the one minute we have left in this meeting
16:00:10 <dag> acozine: my PR does not require changes to module docs
16:00:39 <dag> acozine: it would use the information from the argspec, unless it is also in the documentation (it prioritizes docs over arg_spec for good reason)
16:00:46 <bcoca> dag:  it falls back to current docs?
16:00:52 <bcoca> ah, k
16:00:58 <bcoca> i didnt remember exactly
16:01:11 <dag> the reason for this is that in some cases people want the docs to be different then the implementation
16:01:27 <dag> e.g. type=raw for backward compatibility, but we prefer people to see type=list
16:01:57 <acozine> ah, that's a classic "do what I say, not what I do"
16:02:03 <dag> or there is no default in the arg_spec, but there is a default in the documentation
16:02:26 <dag> because there is a default in the implementation (may be conditional, etc...)
16:02:42 <dag> so the arg_spec is always correct, but not always wanted
16:02:57 <acozine> dag: that makes sense
16:03:45 <acozine> so do you have time (and the desire) to update the PR (again, I know)?
16:03:49 <dag> sure
16:04:26 <acozine> okay, ping me when it's ready for the next round and I'll add it to the Docs WG agenda and suggest it for the Core agenda also
16:04:36 <dag> https://github.com/ansible/ansible/pull/45805#issuecomment-422767850
16:04:54 <dag> The only thing we need to modify is how we use mock in the code
16:05:27 <dag> as per comments from @abadger
16:05:46 <acozine> well, it needs a rebase - I think that's why it's failing CI
16:06:11 <dag> the support for suboptions is another problem, AFAIK suboptions are also currently not support by validate-module
16:06:28 <dag> 3 conflicts
16:06:37 <acozine> they should be pretty easy
16:07:20 <acozine> okay, we're 7 minutes over time for this week
16:07:42 <acozine> thanks kmaxwell bcoca dag Pilou samccann for another great DaWGs meeting
16:07:45 <acozine> #endmeeting