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