15:00:59 <samccann> #startmeeting DAWGs aka Ansible Documentation working group 15:00:59 <zodbot> Meeting started Tue Jul 27 15:00:59 2021 UTC. 15:00:59 <zodbot> This meeting is logged and archived in a public location. 15:00:59 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:00:59 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:00:59 <zodbot> The meeting name has been set to 'dawgs_aka_ansible_documentation_working_group' 15:01:14 <samccann> #chair lmodemal gundalow tadeboro felixfontein 15:01:14 <zodbot> Current chairs: felixfontein gundalow lmodemal samccann tadeboro 15:01:35 <samccann> #topic opening chatter 15:01:41 <abadger1999> Hello 15:01:43 <samccann> Who else do we have around today to talk the docs? 15:01:48 * dericcrago waves 15:01:49 <samccann> #chair abadger1999 15:01:49 <zodbot> Current chairs: abadger1999 felixfontein gundalow lmodemal samccann tadeboro 15:01:55 <samccann> #chair dericcrago 15:01:55 <zodbot> Current chairs: abadger1999 dericcrago felixfontein gundalow lmodemal samccann tadeboro 15:02:10 <felixfontein> good morning to all the ones who just got up ;) 15:03:05 <samccann> briantist andersson007_ dmsimard Xaroth .. anyone else? 15:03:30 <lmodemal> acozine couldn't be here today, but she says "Hello" to everyone :) 15:03:31 <samccann> Just say hi, raise your ascii hand (o/) or anything else to let us know you're around! 15:04:22 <samccann> today's agenda is https://github.com/ansible/community/issues/579#issuecomment-883588842 15:04:44 <samccann> with a followon interesting topic from briantist here - https://github.com/ansible/community/issues/579#issuecomment-883649348 15:04:53 <samccann> So let's get started! 15:05:00 <samccann> #topic Action item review 15:06:17 <samccann> okay I can safely say I didn't nothing assigned to me but one item - 2.9 doesn't have the sphinx problem because our jenkins build pins sphinx to < 4.0 15:06:26 * samccann tries to remember what 'the problem' was 15:06:50 <samccann> ah okay 15:07:15 <samccann> Fedora needs some patches to 2.9 and 2.10 so sphinx 4.x will work. 15:08:02 <samccann> I don't think we have dmsimard here today, but he was going to create two quick patches to those releases to solve the problem for any other distribution that generates docs 15:08:56 <samccann> #info PR to patch 2.9/2.10 to work with sphinx 4 - https://github.com/ansible/ansible/pull/75288 15:09:03 <samccann> Sadly the PR is failing 15:10:14 <samccann> abadger1999 we assigned an action item to you last week - @abadger1999 to look into whether required_if needs more information. 15:10:24 <samccann> Any progress? (any memory what it might even mean?) 15:10:32 <briantist> hey! I'm sort of here 15:10:35 * samccann realizes it's hard to figure out what some of the action items mean 15:10:49 <samccann> Cool briantist ! Hoping we can get to your ideas today 15:10:53 <samccann> #chair briantist 15:10:53 <zodbot> Current chairs: abadger1999 briantist dericcrago felixfontein gundalow lmodemal samccann tadeboro 15:11:14 <abadger1999> samccann: i found that it does not need more info 15:11:42 <samccann> #info required_if does not need more info 15:11:43 <felixfontein> I think the problem is that older sphinx versions (like the one used in CI) really need an instance, while 4.0.0 does not work with one 15:12:03 <abadger1999> It was whether required_if needs a descriptive text or we could construct a standard documentation sentence from what we have to give the argspec 15:12:42 <samccann> #info required_if does not need descriptive test. We can construct a standard documentation sentence from what we have to give the argspec 15:14:41 <samccann> okay going 'way back' on the older action items - we had the documentation generation PR from roles argspecs. abadger1999 - we had an old note that you were looking at the code in that pr to ..erm.. work on parrellel pathways? 15:14:57 <samccann> #info roles documentation from the argspec pr - https://github.com/ansible-community/antsibull/pull/272 15:15:21 <dmsimard> o/ apologies, I missed the ping 15:15:44 <samccann> no worries. welcome dmsimard ! 15:15:49 <samccann> #chair dmsimard 15:15:49 <zodbot> Current chairs: abadger1999 briantist dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro 15:15:58 <dmsimard> I meant to check with fedora packaging if I should work through that patch or if we'd be dropping it anyway (by upgrading to >4.x) but the person was on vacation last week 15:16:13 <abadger1999> Yeah .. are you satisfied with the output of the role docs pr? 15:16:57 <samccann> abadger1999 yeah but let's stage it one more time if there are any code changes? And acozine and I can take another look before merging? 15:17:24 <abadger1999> I've been working to finish the alternate implementation but keep getting side tracked. I think I'd the output is fine, I'll merge today and continue work on the restructuring as a follow-up 15:18:11 <samccann> #info on https://github.com/ansible/ansible/pull/75288 - dmsimar talking with fedora to see what the status is 15:18:17 <abadger1999> samccann: sounds good. Go ahead and stage and then we can merge as is if it looks good 15:19:15 <samccann> felixfontein - actually the staging was through his magic. If the code hasn't changed, then acozine and I can just take a final look before giving it the thumbs up. 15:19:41 <samccann> #action samccann and acozine - review roles docs PR one last time - https://github.com/ansible-community/antsibull/pull/272 to approve 15:19:53 * samccann vows to actually do her action items this week 15:19:57 <felixfontein> :) 15:20:33 <samccann> ok moving on 15:20:52 <samccann> #topic mutually_exclusive added to docs string 15:21:08 <samccann> #link https://github.com/ansible/ansible/pull/74873#issuecomment-880850893 15:21:29 <samccann> Sadly one of the action items I didn't do today (read up on it all to understand the issue). 15:21:44 <samccann> Has anyone else taken a look so we can discuss? Or should we push to next week? 15:22:19 <lmodemal> I didn't get to look into that one...maybe push to next week? 15:22:35 <felixfontein> I'm +1 for including this information - assuming there's also a sanity check which makes sure that if the information is in DOCUMENTATION, it coincides with the information in the argspec 15:22:51 <tadeboro> Sorry all, I need to drop off because I forgot I have some other meeting in 7.75 minutes ... and there is a 10 minut walk to the location. 15:22:58 <tadeboro> #unchair tadeboro 15:22:58 <zodbot> Current chairs: abadger1999 briantist dericcrago dmsimard felixfontein gundalow lmodemal samccann 15:23:00 <felixfontein> tadeboro: run :) 15:23:15 <samccann> thanks tadeboro! 15:23:26 <lmodemal> Thanks tadeboro! 15:24:07 <samccann> #info if we include this item, it needs a sanity check to make sure if the info is in the DOCUMENTATION, it matches the info in the argspec as well 15:25:20 <samccann> okay reading through the PR, it seems there are a number of action items for the PR owner to address. So I think we are in a holding pattern until that happens. 15:25:23 <felixfontein> (the other direction is a bit more complicated since enforcing that info to be present will cause syntax errors when validating with ansible-test from older Ansible versions) 15:26:32 <samccann> ok if there's no more on that item, we can move on 15:27:10 <samccann> I'd like to hop to briantist's item next (not just because it's a fun one... but because... it's a fun one :-) 15:27:18 <lmodemal> lol 15:27:21 <samccann> #topic - rendering collection-level docs 15:27:23 <briantist> 🤩 15:27:25 <felixfontein> :) 15:27:32 <felixfontein> I still have to write the docs I promised... 15:27:38 <samccann> #link https://github.com/ansible/community/issues/579#issuecomment-883649348 15:27:48 <samccann> felixfontein which docs are these? 15:28:01 <felixfontein> a howto on how to create collection docs :) 15:28:14 <samccann> ah gotcha lol 15:28:53 <felixfontein> briantist: :ref: works due to intersphinx btw 15:28:56 <samccann> So the proposal/ask seems something we need, if I define it as 'We need a way for collection maintainers/contributors to generate their docs to validate before they merge their PRs' 15:29:14 <briantist> I'll just say one thing as you read my comment: I tried to separate the desired outcome/intention from implementation ideas. I know that all of the thoughts I have on implementations have holes; purpose of the proposal is maybe the community, with more experience, can come together to get (some approximation of) the desired outcome :) 15:29:41 <samccann> #info - today's problem - a collection contributor has no way to verify any docs changes work until after merging and AFTER uploading to galaxy. 15:29:58 <felixfontein> ...and waiting one more day for devel docs to upate :) 15:30:01 <felixfontein> +d 15:30:24 <briantist> and I'll remind that unlike most of you all here, I have very little direct experience with RST as a format, and almost none with sphinx, so a lot of this feels heavier to me maybe 15:30:31 <samccann> #info and waiting until devel docs pull in that update to docs.ansible.com/ansible/devel. And that only works for collections already in Ansible. 15:31:00 <felixfontein> briantist: my experience with sphinx is also somewhat limited. I was mainly forced to try out more stuff to get some things done :) 15:31:16 <samccann> #info the solution should allow for these contributors to generate the html, have :refs: that work, and not require deep sphinx/rst knowledge 15:31:46 <samccann> well in my perfect world, it would be something as easy as `make webdocs` but for a collection contributor to run 15:31:59 <samccann> and not have ansible/ansible git source locally 15:32:03 <briantist> without samccann 's workaround, there's no way I could have achieved the docs I did, in the timeframe I did; it would have taken weeks, slowly changing/fixing things and doing tons of spurious patch releases just for rendering 15:33:16 <samccann> one thing I wonder - do we want/need this to generate a docsite, or do we need it to generate the html and the contributor just brings up those html pages locally in a browser? 15:33:34 <samccann> `make webdocs` just brings things up locally. 15:34:34 <briantist> it's a good first step for sure, but for docs-only contributors especially, they may not have or want a local development environment to run that in, and I'd love for it to be really easy for folks to make small corrections or additions 15:34:48 <briantist> but I know that complicates things, it could be a later/stretch goal 15:35:35 <briantist> it would certainly be a big help for me as a maintainer 15:35:47 <briantist> (even a local `make docs` thing I mean) 15:35:49 <samccann> here's what I'm thinking. If we had an 'antsibull-collection-docs' option, the contributor would just `pip install antsibull` and then run `antsibull-colleciton-docs' and it would generate all the html etc. It would likely install sphinx and everything else 15:36:24 <samccann> of course I don't code a single thing so that could be just a pipedream :-) 15:36:50 <samccann> felixfontein abadger1999 does that sound possible? ^^ 15:37:20 <abadger1999> I would like just using antsibull-docs to be able to create a functioning docsite (document a collection and links work too the actual ansible docs). It may just need documentation on how to setup and invoke antsibull-docs 15:37:20 <lmodemal> sounds like a good idea samccann, but no clue if it's feasible or not 15:38:08 <briantist> abadger1999: thanks I was just writing about the links part, as one piece I'm very unsure of in generating a separate docsite is whether `:ref:` links to the main docsite would work 15:38:24 <samccann> #info we could extend `antsibull-docs to create a functioning docsite (document a collection and links work to ansible docsite). 15:38:28 <abadger1999> It will if intersphinx is setup 15:38:41 <briantist> I was very unsure about them and it took multiple tries for me to get them right; the workaround of copying my docs into core's docsite helped to ensure they were correct 15:38:44 <briantist> cool! 15:38:45 <samccann> #info we'd need to document how to set up and invoke this locally 15:39:35 <felixfontein> I tihnk sphinx will already be installed as a dependency when installing antsibull, so it should be pretty easy to do 15:39:47 <samccann> abadger1999: so is it just a case of documenting how to do this? as in `antsibull-docs` can do all this already, we just have to write up how to get the bits and bobs installed so it works? 15:40:00 <felixfontein> https://gist.github.com/felixfontein/6de36fff529a12b0c4ffd4aa73a82b6d (when run in an empty directory) will build a small docsite for community.docker and community.crypto 15:40:26 <felixfontein> (would probably be nicer with the Ansible sphinx theme) 15:40:35 <samccann> #info https://gist.github.com/felixfontein/6de36fff529a12b0c4ffd4aa73a82b6d (when run in an empty directory) will build a small docsite for community.docker and community.crypto 15:41:15 <samccann> okay so next steps is to take ^^ and document how it works? 15:41:17 <felixfontein> I can try converting that to a new antsibull-docs subcommand so that you can tell it "build HTML docs for collection(s) X, Y, ..." and it will run something like that 15:41:18 <abadger1999> Yeah, see felixfontein 's script 15:41:58 <samccann> do we need the ability to build multiple collections at the same time? 15:42:09 <samccann> or 'run it in your collection folder' and it works? 15:42:15 <samccann> (for that collection?) 15:42:37 <abadger1999> felixfontein: maybe two commands: antsibull-docs init and then the antsibull-docs collection command you already have 15:42:50 <samccann> cyb-clock-clone sez we are 42 min into the meeting and 15 min into this topic 15:43:25 <samccann> #info maybe two commands: antsibull-docs init and then the antsibull-docs collection command you already have 15:43:36 <felixfontein> abadger1999: what should 'init' do? set up a sphinx site? then building it needs some more commands than just antsibull-docs 15:44:13 <samccann> do we need a sphinx site? or do we need the html like `make webdocs` does locally? 15:44:30 <abadger1999> Yeah setup the sphinx site. Everything in your script except the antsibull-docs collection command 15:44:41 <felixfontein> samccann: `make webdocs` builds a sphinx site :) 15:45:03 <felixfontein> abadger1999: and except the `sphinx-build -M html rst build -c .` call :) 15:45:09 <samccann> ah ok. Was thinking you meant something like that docsite you have up for things like the rolesdocs etc 15:45:30 <felixfontein> samccann: it's basically a simplified version of that docsite 15:45:37 <abadger1999> So the end documentation would be three steps: antsibull-docs init; antsibull-docs collection ; sphinx-build 15:45:39 <samccann> cool 15:46:13 <samccann> could `sphinx-build` be a subcommand of `antsibull-docs collection` ? 15:46:18 <felixfontein> abadger1999: it's probably a good idea to create a script which runs both antsibull-docs and sphinx-build, so you don't have to remember the exact commands 15:46:34 <samccann> so the user just does the init and `antsibull-docs collection -buildhtml` or something? 15:46:53 <samccann> yeah what felixfontein said - the easier the better 15:47:30 <abadger1999> felixfontein: is be okay with that if init spits out an example script that runs out of the box. But i think people might want to tweak the options for their site. 15:47:39 <abadger1999> *i'd be okay 15:48:16 <felixfontein> abadger1999: sure, they can tweak it as much as they want. it's just that it's hard to remember the exact commands to run, and having a script which runs them for you (and which you can adjust) makes it a lot easier :) 15:48:28 <samccann> ah so init creates a file like `build-collections-docs.sh` and the user runs that as is, or tweaks to their hearts desire? 15:48:41 <felixfontein> the scripts could also contain some rsync logic (like my docsite does) so that not everything's regenerated every time 15:48:44 <abadger1999> That sounds good to me 15:49:16 <briantist> yeah I'm fine with tweaking or even creating a script on my own, as long the individual commands are straightforward and make sense; that'd be no problem 15:49:27 <samccann> #info the proposed `antsibull init` command could create an example script that runs out of the box or the user can modify as they want. 15:50:06 <samccann> felixfontein - did you ..ahem... volunteer to do this? ;-) 15:50:23 <felixfontein> samccann: yep :) 15:50:27 * samccann itching to create incomprehensible action items we'll puzzle through next week 15:50:32 <abadger1999> <nod>. I just don't want antsibull-build to get too involved in knowing things that other tools should do (sphinx-build options, setting up rsync, etc). But it's okay if those are in the script with same defaults and the user can tweak them to meet their needs 15:50:32 <samccann> woot! thanks! 15:50:54 <abadger1999> *sane defaulta 15:50:55 <samccann> #info antsibull-build should not get too involved in knowing things that other tools should do (sphinx-build options, setting up rsync, etc). But it's okay if those are in the script with same defaults and the user can tweak them to meet their needs 15:51:08 <samccann> #undo 15:51:08 <zodbot> Removing item from minutes: INFO by samccann at 15:50:55 : antsibull-build should not get too involved in knowing things that other tools should do (sphinx-build options, setting up rsync, etc). But it's okay if those are in the script with same defaults and the user can tweak them to meet their needs 15:51:09 <felixfontein> abadger1999: yep, definitely! 15:51:17 <abadger1999> Cool :-) 15:51:29 <samccann> #info antsibull-build should not get too involved in knowing things that other tools should do (sphinx-build options, setting up rsync, etc). But it's okay if those are in the script with sane defaults and the user can tweak them to meet their needs 15:52:13 <samccann> #action felixfontein to work on creating the script associated with `antsibull` to allow locally generated docsite for collection-level docs 15:52:19 <samccann> woot! Good times! 15:52:40 <samccann> we have 8 minutes left.. .anything else to add here before we open the floor? 15:52:42 <lmodemal> thanks samccann felixfontein for getting that sorted out 15:53:10 <samccann> and abadger199 ... and briantist for the great idea! 15:53:11 <briantist> awesome! looking forward to this, thanks everyone 15:53:29 <felixfontein> briantist: I'll ping you once I have a PR so you can try it :) 15:53:37 <briantist> great! 15:54:00 <lmodemal> abadger1999 briantist felixfontein samccann for the win today! 15:54:06 <samccann> #topic openfloor 15:54:16 <samccann> openfloor... open floor? ah well 15:54:31 <samccann> meanwhile, this is the time to ask or bring up anything about docs! 15:54:48 <felixfontein> are there any news on semantic markup? 15:54:51 <samccann> whether it's your favorite PR or issue that's lingering, or some other docs idea, docs comments... 15:55:15 <samccann> semantic markup is stuck in the 'how do we coordinate across all the users of ansible-docs` hell right now 15:55:33 <samccann> Well, in my mind it is, but maybe we can discuss 15:55:49 <felixfontein> I guess the validate-modules PR will also end up in that hell then :) 15:55:51 <briantist> I'll just add a shoutout to acozine (who I think is not here today) for giving me great feedback over several rounds on my docsite; it's much better for that, so thanks :) 15:56:42 <samccann> like if we (community) add that markup, we can make sure the docsite recognizes it, but what about `ansible-docs`? and what about galaxy-ng - what happens to their docs generation of a bunch of collections start using markup they don't recognize etc. 15:57:13 <samccann> thanks briantist! I'm sure she'll appreciate the shout out when she gets back 15:57:17 <felixfontein> I think we really need some venue where such things that affect all docs consumers (galaxy_ng, ansible navigator, antsibull, validate-modules) and ansible-doc itself can be discussed and where members of all these teams are involved 15:57:24 <samccann> felixfontein - what's the validate-modules PR? 15:57:47 <felixfontein> samccann: https://github.com/ansible/ansible/pull/74873 15:57:48 <samccann> felixfontein - and yep, that's exactly what we are trying to set up... one of those 'ooph we didn't do it yet' action items. 15:57:57 <felixfontein> 'Allow argspec modifiers to be a part of docstring' 15:58:32 <samccann> huh. Wasn't linking that one in my head with all the other pieces that use `ansible-docs`. 15:59:00 <felixfontein> if that information ends up in DOCUMENTATION, all consumers should better know about it (and their programs shouldn't die when they encounter it :) ) 15:59:30 <abadger1999> Yep 16:00:27 <samccann> #info validate-modules PR https://github.com/ansible/ansible/pull/74873 can also impact all the other users of DOCUMENTATION block, including galaxy-ng etc 16:00:36 <samccann> thanks. Wasn't linking that in my head. Good to know 16:00:51 <samccann> We are at the top of the hour.. does anyone else have a quick comment/thought/question before we close out? 16:02:18 <samccann> okay it's a wrap! 16:02:21 <samccann> #endmeeting