16:01:01 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:01:01 <zodbot> Meeting started Tue Nov  9 16:01:01 2021 UTC.
16:01:01 <zodbot> This meeting is logged and archived in a public location.
16:01:01 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:01:01 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:01 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:01:15 <samccann> #topic Opening Chatter
16:01:15 <acozine> o/
16:01:17 <felixfontein> o/
16:01:17 <samccann> Who's around to talk the docs?
16:01:27 <samccann> #chair felixfontein acozine
16:01:27 <zodbot> Current chairs: acozine felixfontein samccann
16:01:30 <ariordan> \o
16:01:54 <samccann> #chair ariordan
16:01:54 <zodbot> Current chairs: acozine ariordan felixfontein samccann
16:02:29 <samccann> #chair felixfontein
16:02:29 <zodbot> Current chairs: acozine ariordan felixfontein samccann
16:02:55 <acozine> double felix!
16:03:17 <felixfontein> hehe :)
16:03:55 <samccann> andersson007_: deric.crago dmsimard0 gundalow tadeboro briantist Xaroth  - you folks around to talk docs today?
16:04:11 <samccann> heh yeah I keep messing up and not getting the right pings here in matrix land
16:04:45 <samccann> meanwhile, let's get started
16:04:51 <samccann> #topic Action Item review
16:05:16 <samccann> #link https://github.com/ansible/community/issues/579#issuecomment-957950690
16:05:37 <samccann> #info core-2.12 docs including japanese translation are all published and done!
16:06:35 <acozine> I think there's an issue somewhere for adding a version-switcher for the Japanese docs
16:06:40 <samccann> #info expand/collapse - ariordan added another example. We can put that up on test later to verify and then we need to coordinate merges as there is a matching antsibull WIP PR for this
16:06:51 <samccann> acozine: yep
16:07:07 <acozine> which makes sense now that there are multiple versions
16:07:12 <felixfontein> the antsibull WIP is unrelated, I only kept it open since it was the only place where a lot of the discussion took place
16:07:20 <samccann> there is a version switcher there but it doesn't work and I havent' had the time to figure out how to get it to work. so for now, there are  three versions on the main language page, yeah
16:07:34 <samccann> heh
16:07:39 <samccann> #undo
16:07:39 <zodbot> Removing item from minutes: INFO by samccann at 16:06:40 : expand/collapse - ariordan added another example. We can put that up on test later to verify and then we need to coordinate merges as there is a matching antsibull WIP PR for this
16:08:19 <samccann> #info expand/collapse -
16:08:19 <samccann> ariordan added another example. We can put that up on test later to verify before we merge
16:08:23 <acozine> hooray for expand/collapse
16:08:27 <samccann> Once we have this functionality, was there something we we going to use it on specifically?
16:08:35 <samccann> other than the occassional super-long output section etc
16:09:37 <acozine> we talked about whether we could use it in the module docs, I think
16:09:43 <acozine> not sure if that's a priority
16:09:57 <felixfontein> I guess starting to use it for large output sections is a good start
16:10:09 <gundalow> Not around today
16:10:10 <acozine> do we have consensus on which versions of everything we're using - in the build and in testing? https://github.com/ansible/ansible/pull/75695/files#r727303757 ?
16:10:14 <samccann> yeah the thing is, the module docs pages already have a convenient TOC at the top to jump to any section you want
16:10:19 <acozine> true
16:10:38 <samccann> acozine: no - we can't get the sphinx version above 3 yet
16:10:50 <acozine> okay, but 3 is confirmed?
16:10:50 <samccann> but since it's now at 2.12, I figure we are at least moving in the right direction
16:10:59 <acozine> heh, fair enough
16:11:12 <samccann> what confirmation do we need beyond the PR itself is passing CI?
16:11:31 <acozine> I was thinking confirmation that CI is actually using 3
16:11:38 <felixfontein> https://github.com/ansible/ansible/pull/75695/files#diff-418649f5e87f149692d365924e50aeae9f5d28cf2d165c451e3829d107614e81R14 says that sphinx 4.0.2 works fine?
16:12:12 <briantist> \o (but I'm really distracted/overbooked)
16:12:34 <acozine> IIRC Sphinx 4 works for the build, but fails CI because of recent changes in core
16:12:38 <ariordan> Here's the link to the file where I added the expand/collapse in the test docs build: http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_vars_facts.html
16:13:11 <samccann> yep, docs build works with 4, CI doesn't so the highest I could go and have it pass CI is 3.
16:13:20 <samccann> > I was thinking confirmation that CI is actually using 3
16:13:20 <samccann> How do we prove that?
16:13:35 <acozine> just confirm with matt clay
16:14:50 <samccann> #action samccann to confirm expand/collapse PR is correctly setting CI to use sphinx 3 with matt clay
16:15:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:15:14 <acozine> d;oh
16:15:17 <samccann> heehee
16:15:25 <acozine> the update is TO the test
16:15:43 <acozine> I'd still confirm with him that it's okay
16:15:47 <acozine> but yeah, looks good
16:15:53 <samccann> heh thanks
16:16:19 <samccann> meanwhile one last look at it based on ariordan 's link about. Are folks happy with this?
16:16:43 <acozine> hrm, I see what he means
16:16:50 <acozine> he wants https://github.com/ansible/ansible/pull/75695/files#diff-418649f5e87f149692d365924e50aeae9f5d28cf2d165c451e3829d107614e81R14 changed back to 3.x
16:17:17 <acozine> ariordan's change to the Ansible Facts page makes it much more readable
16:17:34 <acozine> I might do some styling to the bar that expands the code, though
16:17:53 <acozine> it's easy to skip over it, visually, so if you didn't know the page you might not realize there's anything else there
16:18:05 <acozine> but that can be a separate PR
16:18:21 <samccann> @acozine not sure what you mean - change what back to 3.x? the sphinx version we use today for docs?
16:18:29 <ariordan> I agree: it doesn't look like a code block.
16:19:06 <samccann> I'm not sure what kind of styling is allowed with this extension but we can experiment
16:19:08 <acozine> yeah, what matt meant in his comment, I htink, was that the known_good list should match what we use in CI . . . and he's right, but it feels wrong to dial backwards . . .
16:19:45 <acozine> anywya, this change gets us closer
16:20:15 <samccann> #action samccann ariordan - expermiment with styling of the expand/collapse bar to make it more visually obvious
16:20:35 <samccann> #action samccann to experiment to see if we can set known-good version of sphinx back to 3.0
16:21:03 <samccann> I'm not sure we can go all the way back to 3.0. I have a vague feeling something somewhere is dependent on sphinx >3 but that could just be my imagination
16:22:00 <samccann> meanwhile, the other action item is we don't have docs yet for split controller that landed in 2.12. Still tracking that with the PR owner.
16:22:16 <samccann> Any other action items to review before we move on?
16:22:16 <acozine> if we're going to invest time and effort, it's probably better to invest it in bringing CI up to 4.x
16:22:28 <felixfontein> true
16:22:38 <samccann> acozine: alas beyond my capabilities. It's just a wall of.. urf?? what does this mean??? when I bump it up past 3.
16:22:48 <acozine> heh, yep
16:23:22 <samccann> I can ask gundalow if one of the community-team folks could have a look. Who did you work with before @acozine? Was it matt clay?
16:24:27 <acozine> matt and toshio, I think
16:24:39 <acozine> so yeah, ask gundalow who can help
16:25:38 <samccann> #action samccann to follow up with matt clay and gundalow on how to get sphinx up to 4.x in CI
16:26:28 <acozine> it may be fixable now, my recollection was that attributes and CLI options were the blockers
16:26:38 <acozine> and those are handled in antsibull now
16:26:58 <samccann> ok I'll try it again locally before I bug others
16:27:12 <samccann> #topic docs survey issues
16:27:12 <samccann> meanwhile, new topic
16:27:27 <samccann> #info we need some help fixing  the issues readers told us about in the last survey
16:27:59 <samccann> #link https://github.com/ansible/ansible/issues/75508
16:28:02 <acozine> https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+survey+in%3Atitle
16:28:10 <samccann> This one looks like something someone here or in community might be able to help with
16:28:24 <samccann> Sorry, trying  to go with the tips on playbook into a  role one
16:28:33 <samccann> Anyone here up for giving that a try?
16:29:14 <acozine> I could do a draft that outlines my thinking, that might jumpstart some comments from others who approach the question differently
16:29:38 <samccann> that would be great, thanks!  anything as a start would help
16:29:58 <samccann> #action acozine to draft some ideas on when to convert playbook to role for #75508
16:30:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:30:03 <samccann> Next one https://github.com/ansible/ansible/issues/75506
16:30:27 <samccann> This one looks like it might not be hard.. though brian had some thoughts we'd need to followup on
16:30:31 <samccann> Any volunteers?
16:31:33 <acozine> I could do the first bullet point - make a list of all the pages that use `hosts: all`
16:31:39 <acozine> that would get us a step further on
16:31:50 <samccann> yeah if you can do some grep magic and stick it in the issue, that would help, thanks!
16:32:26 <samccann> #action acozine to  make a list of all the pages that use hosts: all for issue #75506
16:32:55 <samccann> That's definitely a good start on some of these!
16:33:33 <samccann> #topic reviving semantic markup
16:34:00 <samccann> I'm hoping now that 2.12 is out and Ansible 5 doesn't have too much work left from the docs perspective, we can revive this conversation.
16:34:39 <samccann> Last I recall, it was waiting on Red Hat to determine any impact on other module docs output (galaxy-ng/AH, ansible-docs). Does that sound familiar?
16:35:32 <acozine> yeah, that has a familiar ring to it
16:36:38 <samccann> #action samccann to revive Red Hat conversation on semantic markup and impact on ansible-docs and galaxy-ng/AH etc
16:37:10 <felixfontein> \o/
16:37:33 <acozine> it might be worth going back to the DaWGs minutes from a year ago or so when we were discussing the topic regularly
16:37:57 <samccann> yeah I'll do a general review before I start poking folks for input/approval etc
16:38:05 <felixfontein> there's already a PR for antsibull and ansible-doc, so it's mostly things like galaxy-ng/AH, ansible-navigator (in case it formats docs?), and maybe other tools that format docs missing
16:38:46 <samccann> #info there's already a PR for antsibull and ansible-doc, so it's mostly things like galaxy-ng/AH, ansible-navigator (in case it formats docs?), and maybe other tools that format docs missing
16:38:57 <samccann> cool, thanks for  the refresher!
16:39:31 <samccann> #topic community-contributed examples
16:39:34 <samccann> #link https://github.com/ansible-community/community-topics/issues/39
16:39:59 <samccann> Last time we /I paid attention, I think there was general support for the idea.
16:40:32 <acozine> yeah, agreed, I just can't remember what the counter-arguments were
16:41:01 <samccann> yeah flying a little blind here on that as well. Maybe we can action all of us to review and we can delve in more next week?
16:41:16 <bcoca> felixfontein: ansible-navigator does it's own doc construction
16:41:39 <samccann> ooo who sneakin in outa the woodwork today!
16:41:42 <samccann> #chair bcoca
16:41:42 <zodbot> Current chairs: acozine ariordan bcoca felixfontein samccann
16:41:56 <bcoca> got my conflicting meetings cancled!
16:42:21 <samccann> #info ansible-navigator does its own docs construction so also needs to review semantic markup for any potential impacts
16:42:43 <samccann> ok back to community contributed examples -
16:42:45 <felixfontein> doesn't network also have its own docs generator?
16:42:53 <bcoca> a static one, yes
16:43:05 <bcoca> not sure how much it is used now
16:43:09 <samccann> #action all - review https://github.com/ansible-community/community-topics/issues/39 for community contributed examples and let's make some progress on this at our next meeting
16:43:25 <samccann> What doc generator does network have?
16:43:37 <bcoca> felixfontein: my hope is 'sidecar' will unite them all .. to ansible-doc
16:43:40 <samccann> not familiar with that one
16:43:50 <bcoca> samccann: a scrip tthey run to prerender some docs on their collections/repos
16:43:57 <felixfontein> bcoca: it's used for many ansible-maintained collections, like the files in here: https://github.com/ansible-collections/community.aws/tree/main/docs
16:44:02 <samccann> bcoca: how many would `sidecar` unite?
16:44:06 <felixfontein> samccann: ^
16:44:09 <bcoca> hope is 'all'
16:44:22 <felixfontein> bcoca: isn't sidecar about something else?
16:44:36 <samccann> #info network/cloud collections also use their own docs generator to render rst files within their collection repos
16:44:39 <felixfontein> i.e. not about convering `ansible-doc --json` output to some other format?
16:44:44 <bcoca> felixfontein:  ist about adding a few docs features the collections need
16:45:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:45:03 <bcoca> felixfontein: no, but that --json should provide ALL the info that is currently implemented in diff ways
16:45:36 <samccann> @bcoca so if we want semantic markup, then it could be added to sidecar?
16:45:45 <bcoca> so when we add thing like 'retund doc fragments' they all automatically get em
16:46:04 <bcoca> samccann: no, but same as above, if all use ansible-doc they automatically get the 'common things we do'
16:46:13 <bcoca> vs having to reimplement them in 5 places
16:46:21 <felixfontein> is anyone not using ansible-doc?
16:46:37 <felixfontein> (I never looked at the navigator code, but the others I know of use ansible-doc)
16:46:47 <bcoca> for many things the script above, ansible-navigator and in some cases the buidbot
16:47:16 <bcoca> felixfontein: they use it and they also implement their own functions, in many cases conflicting and overlaping
16:47:52 <bcoca> sidecar = add optional yml file to document any/all plugins and allow test/filters to be documented in several ways
16:48:29 <samccann> so for semantic markup, is this something sidecar  docs will help with, or is it not directly involved?
16:49:39 <felixfontein> I think sidecar and semanatic markup are orthogonal, they shouldn't affect each other
16:49:49 <bcoca> sidecar is supposed to fill in missing features others have developed in parallel, so if they use ansible-doc they get any other changes 'for free', including semantic markup removal
16:49:51 <samccann> ok thanks!
16:50:14 <bcoca> but yes, directly unrelated
16:50:22 <samccann> heh ok thanks
16:50:35 <samccann> we have 10 minutes left so let's open the floor for a bit
16:50:39 <samccann> #topic Open Floor
16:50:49 <samccann> This is the time to bring up anything you want related to docs.
16:51:05 <samccann> Favorite/stagnated PR? Issues? Comments?
16:51:40 <bcoca> https://github.com/ansible/ansible/pull/74963 <= planning on taking it up back next week, also planning to document jinja2 filters/tests in core
16:52:19 <felixfontein> I'm looking forward to that!
16:52:54 <samccann> @bcoca cool!  is jinja2 filers/tests docs going to be a separate pr?
16:53:15 <samccann> #info sidecar docs pr https://github.com/ansible/ansible/pull/74963
16:53:47 <samccann> #info jinja2 filters/tests docs coming as well
16:54:12 <bcoca> possibly, that pr already contains some docs but mostly for testing , not sure it will contain complete docs for all or if making a followup makes sense
16:54:17 <acozine> it would be great to see example output from that PR
16:55:19 <samccann> ok 5 minutes left. any other lingering items to talk about today?
16:55:37 <bcoca> https://paste.debian.net/1218821/ <= ansible-doc -t filter ternary
16:57:28 <acozine> cool, thanks
16:59:51 <samccann> ok looks like that's about it for today folks!
16:59:57 <samccann> Thanks everyone!
17:00:00 <samccann> #endmeeting