15:01:48 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:48 <zodbot> Meeting started Tue May  3 15:01:48 2022 UTC.
15:01:48 <zodbot> This meeting is logged and archived in a public location.
15:01:48 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:48 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:48 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:01 <samccann> #topic opening chatter
15:02:02 <acozine> o/
15:02:08 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:35 <felixfontein> o/
15:02:42 <samccann> #chair acozine felixfontein
15:02:42 <zodbot> Current chairs: acozine felixfontein samccann
15:02:42 <acozine> we have plumbers in the house, replacing our water softening system
15:02:43 <acozine> so I may have to step away briefly at random moments
15:02:44 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
15:02:44 <samccann> heh ok
15:02:50 <briantist> o/
15:02:57 <gundalow> In another meeting, I'll read scrollback
15:03:03 <samccann> briantist: around for docs today?
15:03:04 <briantist> here, but in another meeting, may miss stuff
15:03:05 <samccann> oh haha
15:03:08 <samccann> there you are!
15:03:15 <samccann> #chair briantist
15:03:15 <zodbot> Current chairs: acozine briantist felixfontein samccann
15:03:54 <samccann> ok I'm a bit scatterbrained today so may not have much to chat about.
15:04:01 <samccann> #topic Documentation Updates
15:04:20 <samccann> #info working on backports and prep for core-2.13 and Ansible 6 releases
15:04:46 <samccann> #info will revert back to keeping porting guide and release/maintenance pages updated in devel AND latest.
15:05:01 <samccann> aka more backports. We don't have an 'unversioned docs' solution so that's the interim fix for now
15:05:13 <felixfontein> might be helpful to have some 'bot' watching that these don't get out of sync
15:05:36 <samccann> yeah briantist gave me a hint about github actions on that but I haven't had a chance to really dig into it yet
15:06:12 <samccann> right now, I do weekly checks on docs only backports to keep  things in synce until the release. I may just continue that effort indefinitely, or try to get  the GHA stuff working. time will tell
15:07:42 <samccann> on actual docs updates, that's about all I have.
15:07:56 <samccann> Anyone have anything else about words on paper so to speak before we shift  to doctools updates?
15:08:13 <acozine> I heard a nice compliment, related to me third-hand but from a reliable source
15:08:15 <acozine> from pycon
15:08:38 <acozine> apparently someone was heard saying they had chosen Ansible because the docs were so good
15:08:44 <acozine> "I just google my issue and the docs are right there"
15:08:46 <briantist> wow that's great!
15:08:54 <samccann> woot!
15:09:05 <samccann> That's a big congrats to community/developers/users right there
15:09:33 <samccann> folks like me go in and shift things about, but the accuracy and completeness of the docs comes from y'all
15:10:15 <acozine> it's not often you hear unsolicited positive feedback
15:10:32 <samccann> heh yep. Always fun to hear it tho when it comes!
15:10:56 <felixfontein> indeed!
15:11:16 <samccann> #topic doctools
15:11:30 <samccann> #info supporting sidecar docs - https://github.com/ansible-community/antsibull-docs/pull/6
15:11:38 <samccann> felixfontein: wanna give an update on ^^ ?
15:12:07 <felixfontein> yep, sure
15:12:26 <felixfontein> so now that we have the sidecar docs feature merged in devel, we can have docs for filter and test plugins!
15:12:36 <acozine> it's passing CI already, too, that's great
15:12:53 <felixfontein> I tried out adding support for that to antsibull-docs last week, and the PR is the result and I think the results look good :)
15:13:20 <felixfontein> I did some specific changes for test and filter plugins, that also slightly affect how lookup plugins are rendered
15:13:37 <felixfontein> which is the main point I want to ask for your feedback :)
15:13:44 <briantist> those of us using the docs-build stuff in collections can't add those docs until this PR lands (unless you don't try to link to any of them by reference), so I'm looking forward to it!
15:14:12 <briantist> it looks great
15:14:20 <felixfontein> 1. For lookups, the _terms input variable (if present) is now shown in a specific section: https://ansible.fontein.de/collections/ansible/builtin/first_found_lookup.html#terms
15:14:25 <samccann> felixfontein: so you are looking for feedback on the sample output (at least from folks like me who can't look at the code)
15:14:55 <felixfontein> 2. For lookups, if there is a single return value whose name starts with _, it is labelled "Return value" (singular!): https://ansible.fontein.de/collections/ansible/builtin/first_found_lookup.html#return-value
15:15:40 <felixfontein> similar things are used for test and filter plugins, they also distinguish for parameters in three categories: a) input value, b) positional arguments, c) keyword arguments
15:16:08 <felixfontein> input is the thing before | for filters, and before `is` / `is not` for tests
15:16:47 <felixfontein> positional arguments are written behind the filter name / test name without their argument name (| foo(a, b, c, ...)), and keyword arguments are of the form key=value (| foo(k=v, k2=v2, ...))
15:16:59 <felixfontein> https://ansible.fontein.de/collections/ansible/builtin/ternary_filter.html#input for example has all three
15:17:18 <felixfontein> I added little descriptions on what input / positional / keyword args are
15:17:43 <briantist> those are REALLY nice additions felixfontein , very thoughtful
15:17:56 <samccann> yes great stuff indeed
15:18:35 <felixfontein> (eventually I want to change these samples so that they use argument names that actually exist, but for now it uses `positional1`, ... and `key1`, ...)
15:18:53 <acozine> these look great
15:18:58 <samccann> I have a somewhat related question - once we merge this and rev `anstibull-doc`, does this mean we cannot backport any improvements to `anstibull-doc` to 2.13 going forward? (because sidecar docs is a 2.14 feature)?
15:19:30 <felixfontein> also I made `any` a full citizen for return values and input values, and convert `raw` to `any` in all cases (not just for return values)
15:19:37 <felixfontein> (that also affects modules and other plugins)
15:20:20 <felixfontein> samccann: it only processes filters and tests when the ansible-core version used supports them (i.e. if the version is 2.14+)
15:20:34 <felixfontein> the lookup / other plugin changes are independent of the ansible-core version
15:21:43 <samccann> ok thanks for the clarification
15:22:29 <samccann> my goal wrt 2.13 and `antsibull-*` backports is to plan them in advance to to speak. And give core a heads up as well so maybe we an sync up with any other test container changes coming
15:22:53 <felixfontein> that makes total sense
15:23:12 <felixfontein> briantist: thanks for the review :)
15:23:23 <samccann> cool. On this PR, I'm happy w/ the output etc. Anything else holding up the merge?
15:23:26 <felixfontein> if anyone else has formulation improvements / spots typos, happy to fix them once I know off :)
15:23:32 <felixfontein> nope
15:23:47 <felixfontein> I can merge and create a new release, then folks can start using it
15:24:07 <felixfontein> I can also create a PR for devel so that the devel docs can show the new docs (I can also wait with that if you prefer)
15:24:07 <samccann> coolness
15:24:09 <acozine> this opens up another avenue for community-sourced filter examples
15:25:04 <felixfontein> community.general, community.dns and community.routeros already have all their filters and docs documented (at least in their `main` branches)
15:26:31 <briantist> I have a PR open in `community.hashi_vault` for its one filter plugin
15:26:31 <briantist> I just need the above PR so my docs builds don't fail
15:26:41 <samccann> felixfontein: create the devel PR to use the new version but we'll hold on merging until core is ready to do another update to containers.
15:27:04 <samccann> ^^ I can also test run that devel PR on jenkins etc
15:27:06 <felixfontein> samccann: sounds good!
15:27:57 <briantist> I have github-docs-build updates whenever we're ready for that
15:29:15 <samccann> yes that sounds great
15:29:22 <samccann> #topic github docs build update
15:29:24 <samccann> go for it!
15:29:57 <briantist> A GitHub Pages publishing workflow is now available, so we have a nice option for collections to have hosted versions of docs (per branch, per tag, and per PR). I have a Getting Started guide for that, and it's quite easy to set up:
15:29:57 <briantist> https://github.com/ansible-community/github-docs-build/wiki/Getting-started-with-GitHub-Pages
15:29:57 <briantist> And regarding starting with the workflows and actions in general, there are now sample workflows for collection maintainers to grab and use:
15:29:57 <briantist> https://github.com/ansible-community/github-docs-build/tree/main/samples
15:30:57 <briantist> I guess we could use a general "getting started" guide in the wiki, for setting up the workflows, but it will mostly point at the samples, and for GH pages publishing, will point at that guide.
15:31:26 <briantist> But I think we're just about ready to put something out in the Bullhorn and start encouraging folks to enable this.
15:32:21 <samccann> #info getting started on github pages publishing for collection docs PR - https://github.com/ansible-community/github-docs-build/wiki/Getting-started-with-GitHub-Pages
15:32:40 <samccann> #info sample workflows for collection maintainers to grab and use:
15:32:40 <samccann> https://github.com/ansible-community/github-docs-build/tree/main/samples
15:32:43 <briantist> I'm still kind of overloaded at the moment while I prepare for a new minor and new major release of `community.hashi_vault` leading up to the Ansible 6 release, so I might hold off a little on an announcement just so I'm able to provide more help if needed
15:33:08 <briantist> GitHub Pages publishing is live on `community.hashi_vault` and on `lowlydba.sqlserver` collections
15:33:29 <samccann> this all sounds greate briantist !  And yes, holding off on bullhorn until you are ready is good and makes sense.
15:33:46 <samccann> great  greate grreeeaaaatteee!
15:33:48 <samccann> i is a riter
15:34:01 <briantist> haha
15:35:54 <samccann> Some great progress on docs tooling here today. Feels like we need some celebrations or something
15:36:01 <samccann> 🍰 (cake) time!
15:38:09 <samccann> #topic Open Fllor
15:38:13 <samccann> oh my gosh
15:38:15 <samccann> #undo
15:38:15 <zodbot> Removing item from minutes: <MeetBot.items.Topic object at 0x7fccade9f6a0>
15:38:23 <samccann> cannot spell today
15:38:28 <samccann> #topic Open Floor
15:38:34 <samccann> that's better.
15:38:47 <briantist> Open Flor 🌸
15:38:52 <samccann> This is the time anyone can bring up anything about docs and docs tooling. got a topic/issue/PR to discuss? here we go!
15:38:54 <samccann> lol yep
15:40:02 <briantist> if anyone is in this meeting who wants to get a jump on the github docs build, please review what I posted earlier and let me know!
15:41:23 <samccann> ok anyone have anything else or should we end a bit early today?
15:41:48 <felixfontein> never say no to shorter meetings :)
15:42:35 <acozine> sorry, I had to run off to learn about how to flush sediment out of our water system
15:42:46 <acozine> it's fun!
15:42:53 <briantist> 😬
15:43:08 <samccann> hheheh
15:43:31 <acozine> the joys of living in an area with no sewer or water service
15:43:44 <samccann> the joys of well water
15:43:59 <samccann> ok looks like we are winding down so...
15:44:03 <samccann> #endmeeting