15:00:40 <acozine> #startmeeting Documentation Working Group aka DaWGs
15:00:40 <zodbot> Meeting started Tue Jul  6 15:00:40 2021 UTC.
15:00:40 <zodbot> This meeting is logged and archived in a public location.
15:00:40 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:40 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:40 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:00:44 <acozine> #topic opening chatter
15:00:46 <acozine> who's around?
15:00:50 * samccann waves
15:00:57 <acozine> #chair samccann
15:00:57 <zodbot> Current chairs: acozine samccann
15:01:37 <acozine> abadger1999: dericcrago gundalow aminvakil briantist cyberpear felixfontein tadeboro Xaroth zbr you folks talking docs today?
15:01:59 * dericcrago waves
15:02:25 <felixfontein> hi!
15:02:30 <acozine> official agenda: https://github.com/ansible/community/issues/579#issuecomment-870844869
15:02:37 <acozine> hello dericcrago felixfontein !
15:02:38 <felixfontein> welcome back dericcrago!
15:02:41 <acozine> #chair dericcrago felixfontein
15:02:41 <zodbot> Current chairs: acozine dericcrago felixfontein samccann
15:02:59 <acozine> fair warning, samccann and I are just back from a long weekend
15:03:05 * gundalow waves
15:03:16 <acozine> and I, at least, am not fully back in the working mindset yet
15:03:21 <acozine> hi gundalow!
15:03:26 <acozine> #chair gundalow
15:03:26 <zodbot> Current chairs: acozine dericcrago felixfontein gundalow samccann
15:03:49 <samccann> yeah barely remembering how to type here ;-)
15:04:05 <felixfontein> hehe :)
15:04:26 * felixfontein just completed his second workday this week ;)
15:05:12 * acozine must step away for fifteen seconds to let cat out of the bathroom before the neighbors call the ASPCA for all the howling
15:05:38 <samccann> AAAHAHAH
15:05:47 <felixfontein> :)
15:05:49 <acozine> okay, crisis averted
15:05:50 <samccann> poor cat
15:06:24 <acozine> she's fine . . . she's the one who would eat all the other cats' food if she got a chance, so we feed her alone in the bathroom
15:06:34 <samccann> meanwhile I'm making rice to help my dog who isn't eating and I can hear her stomach noises from 6 ft away. It's a DaWGs pets kinda time!
15:06:39 <acozine> heh
15:06:59 <felixfontein> we had one of such cats as well
15:07:12 <felixfontein> he'd just stand next to the others and shove them away
15:07:12 <samccann> DaWGs meeting... come for the documentation, stay for  the pet antics!
15:07:31 <acozine> felixfontein: exactly
15:07:50 <abadger1999> Morning
15:07:58 <felixfontein> good morning abadger1999!
15:07:58 <acozine> hey abadger1999!
15:08:04 <acozine> #chair abadger1999
15:08:04 <zodbot> Current chairs: abadger1999 acozine dericcrago felixfontein gundalow samccann
15:08:21 <felixfontein> I guess there are no news (yet) on docsite (re-)generation?
15:08:59 <abadger1999> Indirectly there is.
15:09:11 <acozine> #topic docsite builds
15:09:21 <acozine> abadger1999:  what's the news?
15:09:44 <abadger1999> samccann verified that it is memory again.
15:09:47 <samccann> What's the chatter... red hatter..?
15:10:00 <acozine> ooh, nice rhyme
15:10:14 <felixfontein> so... maybe red hat happens to have a VM with more than 8 GB RAM? :)
15:10:19 <samccann> heh
15:10:57 <samccann> my local test on a Fedora 34 VM put the  threshold at 8 or above. 7 was too small and failed. 8 worked even with I think 6-8 more collections and 1K more modules
15:11:05 <acozine> I posted a message to the person who manages the Jenkins resources on Friday
15:11:12 <samccann> thanks to abadger1999's hack to allow me to add more collections
15:11:31 <acozine> he may be on vacation, because I haven't heard from him
15:11:57 <samccann> #info local testing on a VM put 7G too low, but 8G ram worked even when adding a handful more collections that totaled over 1K more plugins
15:12:21 <samccann> #info now asking The Powers That Be for more memory for the Jenkins build that runs it all
15:12:39 <samccann> does this mean, btw, that Ansible 4.2? went out but no docs updates yet?
15:12:45 <felixfontein> you could mention that work to adjust the build process to run with less memory costs a lot more than a VM with more memory :)
15:12:54 <felixfontein> samccann: yes
15:12:57 <acozine> samccann: yes
15:12:59 <felixfontein> docs are still for Ansible 4.1
15:12:59 <samccann> sigh
15:13:05 <abadger1999> gundalow: ^ FYI in case we need to start talking to them about paying for new hardware
15:13:19 <gundalow> My credit card is ready
15:13:30 <felixfontein> hardware is usually a lot cheaper than engineer time :)
15:13:36 <gundalow> felixfontein: exactly
15:13:38 <acozine> indeed
15:13:58 <felixfontein> (assuming you don't need very large quantities of hardware ;) )
15:13:59 <samccann> do we remove breadcrumbs again so we can publish if we don't hear back today on more memory?
15:14:19 <acozine> well, for today, can we turn breadcrumbs off? and if we can, is it worse to have fresh docs with no breadcrumbs, or out-of-date docs with breadcrumbs?
15:14:22 <samccann> or is that not 'an easy thing' since the last time all we did was pin antsibull to a lower version
15:14:26 <abadger1999> I have the PR to turn breadcrumbs off in one of my branches still.  I can dust that off so that we can get a build done in the meantime
15:14:52 <acozine> thanks for giving us a workaround
15:14:55 <samccann> yeah probably time to try that
15:15:00 <abadger1999> Cool.
15:15:26 <abadger1999> I'll get a new antsibull package built with that today and we can build with that installed.
15:15:28 <samccann> #action abadger1999 to allow us to turn of breadcrumbs so we can get the docs builds working as an interim fix until we get more Jenkins memory
15:15:52 <samccann> is it worth adding a 'breadcrumbs' toggle switch or is that just more work?
15:16:36 <abadger1999> It is more work but I think it is worthwhile.
15:17:51 <samccann> cool thanks
15:18:02 <abadger1999> I have that PR but it's half-finished.  I'll push the disabled breadcrumbs quickly so that we can get a build working and then work on the toggle afterwards.
15:18:03 <acozine> I might use the switch when building locally
15:18:30 <acozine> to speed things up a bit and give my laptop a break
15:18:36 <abadger1999> (I figure, even if it's two years from now, we'll hit the memory limit again sometime and having the toggle will be nice)
15:18:44 <samccann> agreed
15:18:47 <abadger1999> Cool.
15:18:49 <felixfontein> definitely!
15:19:47 <acozine> #topic action items follow-up
15:20:16 <acozine> the discussion about the build, breadcrumbs, and memory issues was one of our follow-up items
15:20:42 <acozine> heh, actually it was three of them
15:21:02 <acozine> the others were:
15:21:06 <samccann> lol. I might have gone a little crazy with the action items last time ;-)
15:21:28 <acozine> - feedback on the semantic markup plan from the Core and Galaxy teams
15:21:43 <acozine> - problems with PR 73707
15:21:45 <acozine> and
15:22:44 <acozine> - crafting a process for building consensus on changes that affect the docs pipeline, including changes to ansible-doc and more
15:23:11 <acozine> the three things are all related
15:23:21 <acozine> it's not solved (not even close)
15:23:23 <felixfontein> nitz wrote something in the semantic workup issue last week (https://github.com/ansible/ansible/issues/75054#issuecomment-872630039)
15:23:33 <acozine> but we're discussing it at least
15:24:14 * acozine reads nitz's comment
15:25:53 <abadger1999> <nod>
15:26:26 <samccann> nitz comment looks more to do with the URL problems across all the things that display plugin docs
15:26:30 <abadger1999> I think nitzmahone's comment more addresses relative urls in L() and U() than the new semantic macros.
15:27:02 <abadger1999> acozine and I did talk to nitzmahone last week.
15:27:11 <felixfontein> I think it's more on the side of how ansible-doc should resolve links to URLs
15:27:26 <felixfontein> or probably both :)
15:28:02 <felixfontein> abadger1999: with that info I now understand some parts of it better :)
15:28:32 <abadger1999> Yeah.  I think that it only affects ansible-doc output as well (since someone building a website [docs.a.c, galaxy, etc] will know how to resolve relative urls [to their own  site].
15:28:46 <acozine> yeah, he's thinking about things like independently-hosted docsites and command-line output
15:29:12 <samccann> i'm hoping it also reflects how galaxy-ng would handle it all
15:29:30 <felixfontein> apropos: any feedback from the galaxy(-ng) team?
15:29:34 <abadger1999> One of hte things in the talk last week was that nitzmahone had thought that core owned the documentation source format but we said that product said that the docs team owned it.
15:29:41 <abadger1999> He seemed okay with that.
15:29:46 <acozine> felixfontein: unfortunately not
15:30:24 <abadger1999> So he's thinking maybe docs can generate a strict schema for the documentation source format and then "docs tools" would have to conform to that.
15:30:36 <abadger1999> I'm unclear what docs tools is, though, and how they would conform.
15:30:38 <acozine> but merging the more specific conversation (about semantic markup) with the more general conversation (about how AH/Galaxy-ng displays docs) may help engage them
15:31:02 <samccann> true
15:31:03 <felixfontein> hmm, what exactly is 'documentation source format'? the .rst files? or the `ansible-doc --json` output for plugins/roles?
15:31:27 <abadger1999> (he specifically doesn't want CI of ansible-core to test a full docs build and thinks that GIGO applies to ansible-doc --json)
15:31:50 <samccann> cyb-clock-clone wakes up from her stupor to say we are 31 minutes into the meeting and 12 minutes into the current..erm.. jumble of topics ;-)
15:31:57 <abadger1999> felixfontein: I think source format is what's embedded into the plugins and modules.
15:32:11 <felixfontein> ah.
15:32:37 <abadger1999> But ansible-doc --json is also a thing that needs discussion.
15:32:52 <samccann> abadger1999 - CI of ansible-core today tests the manual .rst files right? So it's not testing even the docstrings inside builtin modules in core?
15:33:00 <felixfontein> you mean, whether it should do some transformations/cleanup?
15:33:22 <felixfontein> samccann: I think it's running antsibull on the builtin modules and adding these RST files as well
15:33:22 <abadger1999> At one point, core thought ansible-doc --json should be the single way to get the data from the modules.  But it is not up to that task.
15:33:46 <abadger1999> It should be normalizing its input and failing if it can't if it is to fill that role.
15:33:51 <samccann> given how much downstream depends on 'ansible-doc --json', I'm not sure we can have GIGO (assuming that is garbage in garbage out)
15:34:12 <felixfontein> `ansible-doc --json` has some restrictions that are very annoying (like failing completely if one documentation cannot be serialized)
15:34:14 <acozine> samccann: I believe that is correct - CI runs `rstcheck` on the included .rst files but it doesn't run the docs buld
15:34:19 <acozine> s/buld/build
15:34:47 <abadger1999> samccann: I think there is a test of documentation extracted from builtin modules.
15:34:57 <felixfontein> https://github.com/ansible/ansible/blob/devel/test/sanity/code-smell/docs-build.py#L33
15:35:01 <abadger1999> it's the ansible-test sanity docs-build test.
15:35:25 <abadger1999> felixfontein: is quicker than me today :-)
15:35:47 * felixfontein knows the test/ directory pretty well ;)
15:35:58 <acozine> heh
15:36:51 <samccann> ah ok so ansible-core CI tests  the equivalent of make coredocs?
15:37:12 <abadger1999> yep (the singlehtml version of coredocs)
15:38:37 <samccann> ok we are up to 20 min on this topic...how do we move foward?
15:38:58 <samccann> is it keep pushing on the existing action items and discussions, or something in addition to that?
15:39:17 <abadger1999> We definitely need to keep talking with nitzmahone about this.
15:39:19 <acozine> yes
15:39:31 <samccann> <nods>
15:39:34 <abadger1999> We have several breaking changes from core that are in limbo right now.
15:39:45 <gundalow> #unchair gundalow
15:39:45 <zodbot> Current chairs: abadger1999 acozine dericcrago felixfontein samccann
15:39:52 <gundalow> (got to step away)
15:40:03 <acozine> I'm thinking if we can come up with a list of goals, we can evaluate potential solutions to the problem by how well they meet those goals
15:40:12 <abadger1999> Not sure if we want to push for those to be reverted until we get the changes to docsite to deal with them as well.
15:40:14 <felixfontein> abadger1999: you mean relative links in L() and attributes?
15:40:18 <acozine> bye gundalow
15:40:42 <felixfontein> s/links/URLs/
15:40:44 <abadger1999> yeah.  And the third is adding new fields to the ssh connection plugin
15:40:45 <samccann> acozine - so like a hackmd we can use to drive the discussion on its multiple 'release the kracken' fronts?
15:41:03 <felixfontein> ah right
15:41:09 <felixfontein> (the cli field)
15:41:23 <acozine> samccann yeah, that's what I was thinking
15:42:00 <samccann> #action samccann acozine to get a hackmd or something to come up with a list of goals, we can evaluate potential solutions to the problem by how well they meet those goals
15:42:02 <acozine> often in the past we've gotten mired in the discussion about whether a particular change is good or bad, or about who should bear the consequences of a particular change
15:42:40 <acozine> if we have an agreed-upon set of goals, maybe we can avoid that type of discussion
15:43:38 <samccann> does all this have enuf tentacles at this point that we need a project board to keep track? Like to list all the PRs that may need backporting, the semantic markup PRs or issues, and the url proposal from nitz?
15:44:03 <samccann> or am I just asleep at the keyboard and most of this is tracked somewheres already?
15:44:08 <felixfontein> hmm, maybe a project board would be nice :)
15:45:59 <samccann> before I slap one up, abadger1999 - did the project board I tossed up like a year or so ago with the docs pipeline stuff (aka creating antsibull) prove helpful?
15:46:56 <abadger1999> Not for me but it wasn't a burden for me to make sure the tickets I had on it were  up to date.
15:47:11 <abadger1999> Iit is useful to have all information consolidated in one place.
15:47:35 <abadger1999> For me, tough, I find a single document easier to work with than a project board where you have to click links to drill down.
15:47:51 <abadger1999> (Just personal preference)
15:48:15 <felixfontein> a single document is also good. just something that's more flexible than a GH issue :)
15:48:21 <abadger1999> Yeah :-)
15:48:49 <samccann> ok I can go either way. I'm happy to create a project board if folks like it, or yeah, we just use the hackmd document we talked about creating above
15:49:22 <acozine> maybe we start with the hackmd, then see how many links we're putting in for github issues and PRs
15:49:26 <acozine> if it's mostly just that
15:49:34 <acozine> then we can set up a project board
15:49:44 <felixfontein> sounds good to me
15:49:56 <samccann> cool
15:50:17 <samccann> cybclock-clone sez we are 50 minutes into the meeting and 30 into this topic
15:50:58 <acozine> this issue, or nest of issues, is a blocker for most other things we've been talking about
15:51:10 <acozine> I think we try to make some headway on that this week
15:51:17 <abadger1999> I will work with whichever you want to use :-)
15:51:19 <felixfontein> yep, that would be great :)
15:51:19 <acozine> and revisit everything else next Tuesday
15:51:30 <acozine> great
15:51:37 <acozine> okay, quick open floor, then
15:51:43 <acozine> #topic open floor
15:52:00 <acozine> any issues, PRs, questions, concerns, ideas, etc. are now welcome
15:52:08 <felixfontein> https://github.com/ansible-community/antsibull/pull/272 (role docs) is not blocked by the above though :)
15:53:05 <acozine> heh
15:53:33 <acozine> what is the current state of that PR?
15:53:37 <samccann> oo fun!
15:53:47 <acozine> felixfontein: are you looking for more reviews?
15:53:53 <acozine> or do you think it's ready to merge?
15:54:02 * acozine reads a bit
15:54:12 <abadger1999> <nod> I was working on changing the code to use a parallel pathway instead of conditionals scattered throughout.
15:54:26 <abadger1999> IIRC, the output had been approved?
15:54:37 <felixfontein> I have no idea whether the output is approved or not
15:54:50 <felixfontein> (I'm just seeing that my docsite has a CSS problem though)
15:55:25 <abadger1999> Hmmm... I know we talked about it a few meetings ago but yeah, no record on the PR.
15:55:26 <felixfontein> the interesting case are probably roles which have multiple entrypoints, like the ones in sensu.sensu_go (example: https://ansible.fontein.de/collections/sensu/sensu_go/agent_role.html#ansible-collections-sensu-sensu-go-agent-role)
15:55:42 <felixfontein> (the TOC CSS seems broken)
15:55:59 <abadger1999> acozine, samccann : If you want to review the output and apprve/make suggestions on changes, I can work on the structure of the code in parallel.
15:56:13 <samccann> sounds good to me
15:56:48 <acozine> agreed that multiple-entry-point roles are tougher to document
15:56:55 <acozine> examples would help
15:56:57 <samccann> #action samccann acozine to review roles output etc from https://github.com/ansible-community/antsibull/pull/272
15:57:08 <samccann> #info interesting case are probably roles which have multiple entrypoints, like the ones in sensu.sensu_go (example: https://ansible.fontein.de/collections/sensu/sensu_go/agent_role.html#ansible-collections-sensu-sensu-go-agent-role)
15:57:59 <samccann> #action abadger1999 to also work on the structure of the code for that PR to use parallel pathways
15:58:01 <acozine> cool!
15:58:25 <acozine> other open floor items?
15:58:38 <felixfontein> (CSS is fixed if you reload)
15:58:47 <acozine> that was fast!
15:58:55 <abadger1999> Nice :-)
15:59:19 <felixfontein> I upgraded/reinstalled sphinx, the theme, etc., and rebuild it... no idea what went wrong, but now it's fixed :)
15:59:36 <acozine> ah, the mystery fix
15:59:41 <acozine> my favorite
16:00:01 <felixfontein> acozine: it's probably not yet a good idea to merge https://github.com/ansible/ansible/pull/74704 since there's no release of the collection with the guide in it
16:00:24 <acozine> oh, good point
16:00:41 <acozine> although, the guide will still appear in the 2.11 docs
16:00:51 <acozine> I won't backport the change
16:01:17 <felixfontein> true. it will just be gone on devel. assuming that devel is eventually rebuilt ;)
16:01:19 <acozine> the devel docs will be affected
16:01:36 <acozine> but hopefully not for long, now that we can build from the most recent collections
16:01:43 <acozine> heh, true
16:02:02 <acozine> maybe the fix to the build and the next collection release will coincide
16:02:28 <felixfontein> would be nice :) though I'm not sure, I think they're working on 2.0.0 right now, and that might take some more time
16:02:31 <samccann> so is the process to move the guide to a collection, get the collection up on galaxy, then remove the guide from ansible/ansible?
16:02:42 <samccann> assuming devel docs will pick up that new collection asap?
16:02:47 <acozine> yeah
16:03:01 <acozine> I just got out ahead of myself
16:03:02 <samccann> ah but that collection isn't releasing yet cuz it's a big one coming?
16:03:07 <abadger1999> I'll merge and releasethe simple disable right after the meeting: https://github.com/ansible-community/antsibull/pull/287
16:03:14 <abadger1999> Then we can rebuild the docs.
16:03:23 <samccann> cool thanks!
16:03:32 <samccann> we are 3 min over sez cyb-clock-clone
16:03:37 <felixfontein> samccann: that's my guess, but it could be wrong :)
16:04:00 <felixfontein> just asked in #ansible-aws
16:04:46 <acozine> I'm late for my next meeting
16:04:57 <samccann> ooch ok time to wrap up
16:05:19 <felixfontein> acozine: btw you had a typo in https://github.com/ansible/ansible/pull/74704#issuecomment-874867541, so it probably won't get merged anyway until you fix it :)
16:05:21 <samccann> i'll end meeting in a minute unless someone else pipes up
16:05:28 <acozine> thanks abadger1999 dericcrago felixfontein gundalow samccann
16:05:41 <acozine> felixfontein: saved by a typo!
16:05:44 <felixfontein> the next amazon.aws release will probably be this month, and it will be 2.0.0
16:05:51 <felixfontein> acozine: yes :D
16:05:56 <felixfontein> thanks everyone!
16:07:21 <samccann> #endmeeting