15:31:20 <acozine> #startmeeting Ansible Documentation Working Group aka DaWGs
15:31:20 <zodbot> Meeting started Tue Dec  4 15:31:20 2018 UTC.
15:31:20 <zodbot> This meeting is logged and archived in a public location.
15:31:20 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:31:20 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:31:20 <zodbot> The meeting name has been set to 'ansible_documentation_working_group_aka_dawgs'
15:31:31 <acozine> who else is around?
15:31:48 <dj3ei> I am.
15:31:58 <samccann> here
15:32:11 <acozine> #chair samccann dj3ei
15:32:11 <zodbot> Current chairs: acozine dj3ei samccann
15:32:32 <acozine> dj3ei: I'll have to get used to your IRC nick
15:33:00 <acozine> Xaroth: you around?
15:33:05 <aknrdureegaesr> I'll tried to use my github name as a nick.
15:33:42 <acozine> #chair
15:33:42 <zodbot> Current chairs: acozine dj3ei samccann
15:35:17 <acozine> hmm . . . looks like we lost Andeas . . . I don't see either of his nicks now
15:35:20 * gundalow waves
15:35:26 <acozine> #chair gundalow
15:35:26 <zodbot> Current chairs: acozine dj3ei gundalow samccann
15:35:36 <acozine> s/Andeas/Andreas
15:35:51 <gundalow> shaps: yo
15:36:06 <gundalow> acozine: you mean shaps?
15:36:25 <dj3ei> (Sorry - my IRC client crashed under me. Now I'm back.)
15:36:33 <acozine> gundalow: nope, dj3ei aka aknrdureegaesr
15:36:49 <acozine> welcome back!
15:36:57 <dj3ei> Thanks!
15:37:40 <acozine> okay, first order of business is dj3ei's PR that pulls the docstrings of the module_utils into the docsite
15:38:25 <acozine> link to PR: https://github.com/ansible/ansible/pull/48416
15:38:44 <acozine> current page (would be replaced): https://docs.ansible.com/ansible/devel/reference_appendices/module_utils.html
15:39:20 <dj3ei> And the new version is https://www.famsik.de/ansible/reference_appendices/module_utils .
15:39:20 <acozine> page rendered from the PR's branch: https://www.famsik.de/ansible/reference_appendices/module_utils
15:39:27 <acozine> jinx!
15:40:28 <acozine> dj3ei: do you have a copy of the .rst file from which the .html was built?
15:40:42 <dj3ei> It's in the pull request...
15:41:13 <dj3ei> https://github.com/ansible/ansible/pull/48416/files
15:41:24 <acozine> sorry, that wasn't clear
15:41:45 <dj3ei> https://github.com/ansible/ansible/pull/48416/files#diff-adac8c579f3cd773f73a0fc4611b4089 more precisely
15:42:30 <dj3ei> For the modules, the entire .rst file is generated. This has not been the case for this one, before, and I did not change that.
15:42:49 <acozine> yeah, this is a really nice improvement
15:43:02 <gundalow> +1,000
15:43:11 <acozine> what I'd like to look at is the intermediate rst, with the details of each entry
15:43:15 <gundalow> I wonder if example uses of (say) argspec would go into the Python file, or directly in a RST file. Ie would we have a "high level examples page" which links to this new auto generated page "reference material"
15:43:23 <acozine> because I'd like to see what the anchors look like
15:43:35 <Xaroth> acozine ish, yes
15:43:54 <acozine> in other words, if I wanted to link to one of these lovely new entries, how would I do that/
15:43:57 <acozine> ?
15:44:05 <acozine> #chair Xaroth
15:44:05 <zodbot> Current chairs: Xaroth acozine dj3ei gundalow samccann
15:44:25 <dj3ei> I'm not sure there _is_ an intermediate .rst file. This goes straight into sphinx.
15:45:42 <dj3ei> I do a link to the documentation at https://github.com/ansible/ansible/pull/48416/files#diff-780d343ce8b883ceac90a850c6760133 : :ref:`documentation page <ansible.module_utils>`
15:46:33 <acozine> yeah
15:47:02 <dj3ei> If you want to link into a specific method or so, I'm not sure myself - we'd need to consult the sphinx documentation.
15:47:24 <acozine> it looks like sphinx adds anchors . . . at least, in the html I can specify a method: https://www.famsik.de/ansible/reference_appendices/module_utils#ansible.module_utils.basic.AnsibleModule.boolean
15:47:33 <acozine> which suggests that I could link to that from elsewhere in the docs
15:48:08 <dj3ei> The official word should be in http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html somewhere.
15:49:22 <acozine> ah, that makes sense
15:50:10 <acozine> for the module docs, we run each module through an Ansible template, but since these are all on a single page, that wouldn't make a lot of sense
15:51:11 <acozine> anyway, I see this as a definite improvement over what we have now
15:51:30 <samccann> yes big +1 for the improvement!
15:51:33 <dj3ei> Yes. I was not yet aiming for the perfect, but only for the better.
15:51:34 <dj3ei> Thanks!
15:51:43 <acozine> and we can link to the page for sure, even if we can't link to individual methods (and we might be able to do that anyway)
15:52:15 <dj3ei> I have not found it right away in the docs, but I speculate it should be possible somehow.
15:52:42 <acozine> gundalow: I missed your comment or question about example uses . . . care to restate?
15:52:43 <samccann> the only nit I have is here - https://github.com/ansible/ansible/pull/48416/files#diff-adac8c579f3cd773f73a0fc4611b4089R15
15:53:13 <samccann> seems like the `from` should be outside the backticks? (``  dunno what they are called)
15:53:33 <gundalow> Would something like https://github.com/gundalow/ansible/blob/docs-argspec/docs/docsite/rst/dev_guide/module_utils/basic.rst go into `module_utils/basic.py`'s Python comments, or in standard RST, and we'd links to the autogenerated docs?
15:53:40 <gundalow> Just wondering how this would be used in anger
15:53:56 <acozine> samccann: nice catch - I think it should be either "via" or "from" but not both
15:53:58 <dj3ei> That is supposed be a line of Python
15:53:59 <dj3ei> from ansible.module_utils.basic import AnsibleModule
15:54:54 <acozine> dj3ei: ah, so rephrasing the sentence would help then: "To use this functionality, include `from xxxx` in your module"
15:55:06 <acozine> something like that
15:55:17 <samccann> ah ok, yeah that's clearer to me
15:55:19 <dj3ei> And the "via" was supposed to be English. It was clear to me, but isn't clear to you, so we should re-phrase, yes.
15:57:04 <acozine> gundalow: that page is a WIP?
15:57:09 <dj3ei> I have found another nit myself: https://www.famsik.de/ansible/reference_appendices/module_utils#ansible.module_utils.basic.AnsibleModule.is_executable does not document the parameter in the (), but I just saw in the sphinx documentation how to do it.
15:57:33 <gundalow> acozine: Just using that as an example of something not currently documented
15:58:46 <dj3ei> You can put links into Python docstrings that will be picked up when the doc is autogenerated.
15:59:29 <acozine> gundalow: So the question is, how can we expand on the framework from this PR to document other things?
15:59:31 <dj3ei> My patch essentially turns the docstrings into .rst format. I was bitten by that and had to fix a few things before it would even auto-generate.
16:00:11 <acozine> dj3ei: yeah, it's not as intuitive as you'd expect, given that Sphinx was basically written to do exactly that
16:01:09 <dj3ei> acozine: Yes, but I think this is a GOOD thing. It opens up options to answer gundalow: 's concerns.
16:01:24 <acozine> dj3ei: agreed
16:01:53 <gundalow> well, should that table be documented in `basic.py`, or do we see the autogenerated as reference material, and we link from elsewhere
16:03:20 <dj3ei> Philosophically, you can squeeze a lot of documentation into the doc strings or else have a separate page that documents some aspect in details. Personally, I would tend to put the argument spec documentation elsewhere, but with the docstrings being rst, one can (and should!) link from the docstring to that elsewhere-place.
16:03:32 <acozine> I think the autogenerated stuff is reference material for developers who already know how to use module utilities  and need the details of a particular method
16:03:42 <dj3ei> That's true!
16:04:17 <gundalow> dj3ei: +1 to that
16:04:22 <dj3ei> And it would be a bug if the reference material did not offer easy access to more in-depth documentation of aspects.
16:04:41 <dj3ei> But that does not mean that those aspects need to be documented right there. That's what links are for! :-)
16:04:53 <gundalow> so https://github.com/gundalow/ansible/blob/docs-argspec/docs/docsite/rst/dev_guide/module_utils/basic.rst would be a page under `dev_guide` somewhere and it would say "for the full list of `types` see LINK_TO_BASIC.PY
16:04:57 <acozine> If there's a need for narrative documentation on "how to use module utilities" it belongs in the dev guide as rst and we link to the reference stuff
16:05:37 <dj3ei> acozine: +1 to that from me.
16:06:12 <dj3ei> Being a developer myself, that's the expectations with which I approach documentation sites.
16:07:30 <acozine> gundalow: I like the basic.py stuff you've got too, and it would be great to merge that in
16:08:01 <gundalow> acozine: Yup. Need to find a home for it
16:08:31 <acozine> gundalow: is finding it a home, or designating a home for it, a blocker for the module_utils PR?
16:10:01 <gundalow> acozine: blocker for my argsec PR
16:10:16 <gundalow> I'm happy for module_utils PR to be merged
16:10:18 <dj3ei> We have found a need for a rephrase and some stuff that should go into some () to improve #48416. Should I change the title to "WIP", fix that, remove the WIP, and then throw it back over someone's fence? Or what is a good procedure now?
16:11:04 <dj3ei> s/some stuff/a parameter's name/
16:11:08 <acozine> samccann: can you do a "suggested" change for the rephrasing while dj3ei works on including the `()` content?
16:12:00 <acozine> dj3ei:  what is your expected timeframe for the changes you have in mind?
16:12:14 <acozine> days? weeks? some time in the hazy future?
16:12:15 <dj3ei> Tomorrow evening or so.
16:12:26 <dj3ei> This week certainly!
16:12:37 <acozine> ah, on that timeframe there's no need to mark it WIP
16:12:44 <dj3ei> Ok.
16:13:13 <dj3ei> (I program transaction and parallel stuff, too, ...) :-D
16:13:27 <acozine> we're working through the backlog, but unfortunately we've still got "active" PRs that are months and months old
16:13:47 <samccann> suggestion added
16:13:52 <acozine> drat, I forgot to set a topic
16:14:09 <acozine> samccann: thanks
16:14:28 <dj3ei> samccann: Thanks. Good improvment!
16:15:08 <samccann> acozine: I'll tiptoe through and add topic/infos based on what we have here
16:15:23 <acozine> samccann: thanks!
16:15:47 <samccann> #topic pulling module_utils docs out of the docstrings
16:15:57 <samccann> #info https://github.com/ansible/ansible/pull/48416
16:16:32 <samccann> #info replaces this page https://docs.ansible.com/ansible/devel/reference_appendices/module_utils.html
16:16:44 <acozine> dj3ei: when the PR is ready for re-review, please post a note in this channel
16:17:02 <dj3ei> That'll be easy.
16:17:05 <dj3ei> Thanks!
16:18:10 <acozine> we've got about ten more minutes
16:18:14 <samccann> #action dj3ei to add some improvements to the PR and remove WIP from the title. Post in this irc when ready to merge
16:19:03 <dj3ei> There is no "WIP" in the title last time I looked.
16:19:12 <acozine> #topic removing duplicate sphinx theme
16:19:27 <samccann> oh sorry...must have picked that up from the wrong thread
16:19:55 <acozine> there's a nice clean PR from Xaroth that removes the `srtd` theme: https://github.com/ansible/ansible/pull/49289
16:19:57 <dj3ei> samccann: I suggested WIP, but acozine said not needed for a few days.
16:20:01 <dj3ei> One more question: I'd usually squash the whole thing into one Git commit. Is that what you prefer, too?
16:20:31 <acozine> dj3ei: no need, since we squash-and-merge when we merge
16:21:01 <dj3ei> But also doesn't hurt and I can do it as I usually do.
16:21:17 <acozine> dj3ei: you can do it if you like, yes
16:21:24 <gundalow> acozine: Given your last comment on 49289 do we need to build on test server to check how `note` `warning` look?
16:21:37 <dj3ei> Ok, then I'm all set. Thanks all around!
16:22:04 <acozine> gundalow: good idea
16:22:21 <acozine> based on local testing it should work, but it never hurts to check
16:22:58 <acozine> this is one we'll want to merge early in the week, out of respect for the law of unintended consequences
16:23:17 <samccann> #info removing the `srtd` theme: https://github.com/ansible/ansible/pull/49289
16:23:55 <samccann> #action acozine to build49289 to the test server to check how `note1 and `warning` look
16:24:15 <acozine> I'm 99.9% sure it will be fine
16:24:18 <samccann> geez.  need remedial typing skills!
16:24:43 <samccann> how do I back out that last action and correct it so it's not wiggy?
16:24:57 <Xaroth> undo? I think
16:25:12 <gundalow> #undo
16:25:12 <zodbot> Removing item from minutes: ACTION by samccann at 16:23:55 : acozine to build49289 to the test server to check how `note1 and `warning` look
16:25:34 <samccann> thanks gundalow!
16:25:46 <Xaroth> acozine: not sure if you saw my notes from after our discussion; reducing the maximum depth of navigation menu doesn't do a whole lot for docs building time, the only impact is file size reduction.. the main cause of it taking so long is the fact you're putting 3000 files together into one.
16:26:06 <samccann> #action  acozine to build PR49289 to the test server to check how `note` and `warning` look
16:27:12 <acozine> oh, I recently noticed an unrelated CSS thing - when we changed the background color for code snippets from that yellow-green color to GitHub Gray, we missed the style for `emphasis`
16:27:52 <acozine> we only use it on one page, but it's still bright yellow and is now a larger font than the rest of the paragraph, so it obscures the text around it
16:28:18 <acozine> Xaroth: thanks for testing the build times
16:29:56 <samccann> #info Xaroth experimented with doc build times - seems the long time is due to pulling 3k files into one
16:30:24 <acozine> Xaroth: it's too bad we don't have an easy way to reduce the build time, but I'm glad we have freedom to experiment with the navigation menu without making things worse
16:31:26 <acozine> file storage space is cheap, so if a really good docsite ends up being large, that's fine
16:32:13 <acozine> thanks for a great meeting, DaWGs
16:32:45 <acozine> next week let's look at more of the "mechanical" docs PRs
16:33:30 <acozine> #endmeeting