15:01:52 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:52 <zodbot> Meeting started Tue Sep 13 15:01:52 2022 UTC.
15:01:52 <zodbot> This meeting is logged and archived in a public location.
15:01:52 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:52 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:52 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:14 <samccann> #topic opening chatter
15:02:16 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:25 <DonNaro[m]> o/
15:02:27 <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:28 <DonNaro[m]> welcome back
15:02:35 <acozine> o/
15:02:36 <DonNaro[m]> double booked but I'm around
15:02:41 <samccann> #chair Don Naro acozine
15:02:41 <zodbot> Current chairs: Don Naro acozine samccann
15:02:48 <samccann> thanks!
15:03:10 <samccann> briantist: tremble felixfontein around to talk docs todday?
15:04:09 <samccann> Official agenda at https://github.com/ansible/community/issues/643#issuecomment-1231967346
15:05:14 <samccann> hmm could be a quiet day
15:05:25 <acozine> seems like it, yeah
15:05:34 <samccann> #topic Action Item updates:
15:05:35 <acozine> where are we on the schedule for the next release?
15:05:48 <acozine> I mean, when is the core freeze?
15:05:52 <felixfontein> o/
15:06:02 * acozine searches for that page that lists the dates
15:06:11 <tremble> o/
15:06:29 <acozine> #chair felixfontein tremble
15:06:29 <zodbot> Current chairs: Don Naro acozine felixfontein samccann tremble
15:06:43 * acozine waves
15:06:57 <samccann> #info core freeze is Sept 19
15:07:09 <samccann> #info resolved action item - https://github.com/ansible/ansible/pull/78668
15:07:14 <acozine> ooof, that's really soon
15:07:32 <samccann> that it is
15:08:03 <felixfontein> indeed
15:08:07 <samccann> #topic Core Freeze
15:08:13 <tremble> That's only for core though?  The big bucket with collections has another month or so?
15:08:16 <samccann> yep
15:08:31 <samccann> I don't have that date handy but it's usually 3 weeks later, yep.
15:08:59 <samccann> #info items to complete before core freeze:
15:09:13 <samccann> #info update docs build dependencies (keeping rstcheck < 6 for now)
15:09:36 <samccann> #info merge of https://github.com/ansible/ansible/pull/78700 so new filter/test plugins display correctly
15:09:54 <samccann> #info possible update to antsibull-docs based on results of #78700
15:09:59 <felixfontein> and possibly add some filter docs, because right now there aren't that many
15:10:03 <samccann> Anything else come to mind that has to happen by Fridday
15:10:15 <felixfontein> though that can also happen in the next weeks, I guess
15:10:27 <samccann> felixfontein: is there a PR with that yet?
15:10:48 <samccann> Yeah, if it's just docstrings, I can merge and backport up until core RC at least
15:11:17 <samccann> #info would be good to have more filter docs as there aren't many yet with the new sidecar docs feature in 2.14
15:11:28 <felixfontein> samccann: there is only mine (with a handful), bcoca wanted to have one with more filter docs but I don't think it's there yet
15:12:11 <samccann> felixfontein: is there anything holding up your PR? is it 78700 holding it up?
15:12:29 <samccann> (shertel's PR that will go in hopefully on Thurs?)
15:13:23 <felixfontein> my PR is independent, it's mainly waiting for reviews, and it was kind of blocked because bcoca said his PR covers all the filters mentioned in it
15:13:37 <felixfontein> but then he later said that he might omit the filters in my PR
15:13:46 <felixfontein> so I don't really know what will happen now :)
15:14:38 <samccann> what's your PR, do you have it handy? (for the minutes)
15:15:04 <felixfontein> https://github.com/ansible/ansible/pull/78548
15:16:39 <samccann> #action samccann to clarify w bcoca on whether he is omitting filter docs from https://github.com/ansible/ansible/pull/78548 in his filter docs PR
15:16:59 <samccann> hopefully that will make sense to me in a couple of days  when I go back to look at open action items :-)
15:17:11 <bcoca> felixfontein: go ahead with yours, 'ill just remove already documented from branch
15:17:18 <samccann> #info open action item - Create tracking issue 'somewhere' to track all the collections that SHOULD consider using true/false boolean in examples (tho some may not want to for $REASONS)
15:17:18 <samccann> 
15:17:20 <bcoca> also .. submit branch ...
15:17:43 <samccann> oh nice! action item resolved already :-) thanks bcoca
15:17:59 <bcoca> https://github.com/ansible/ansible/issues/78760
15:18:09 <bcoca> just to balance it out, adding new one
15:18:17 <bcoca> ;-p\
15:18:31 <acozine> heh
15:18:38 <acozine> "Close all the issues you want, we'll make more"?
15:18:42 <samccann> hahaha
15:19:12 <samccann> ok I'll take a look and comment in the issue. Some of that was done 'on purpose' but w/o realizing the links are now missing for generated links
15:19:47 <briantist> o/
15:19:57 <briantist> sorry, triple+ booked basically
15:20:10 <samccann> bcoca - links generated by core - does that mean links used in ansible-doc or something else?
15:20:17 <samccann> #chair briantist
15:20:17 <zodbot> Current chairs: Don Naro acozine briantist felixfontein samccann tremble
15:20:26 <bcoca> samccann or in error messages
15:20:32 <felixfontein> (sorry, just switched floor and machine)
15:20:36 <bcoca> basically 'by the cli tools'
15:20:40 <samccann> ok thanks
15:21:27 <bcoca> sorry, confusing issues, ticket is just about the site
15:21:31 <bcoca> docsite
15:21:55 <samccann> heh. okay so in that issue, the problem is there are places on the docsite trying to link to ...places no longer on the docsite?
15:21:57 <bcoca> the cli link generation is diff issue, solved only for core refs, still and issue for others
15:23:13 <samccann> #topic Documentation updates
15:23:19 <samccann> #info archiving 2.3 docs archive is at https://docs.ansible.com/archive/ansible/2.3/. Redirects coming soon for older urls .
15:23:39 <samccann> I keep saying 'redirects coming soon'  but you know.. soon is relative based on other priorities :-)
15:23:44 <samccann> but we're getting there
15:24:45 <samccann> #info User guide high-level restructure complete - https://docs.ansible.com/ansible-core/devel/index.html Feedback welcome
15:24:53 <samccann> kudos to Don Naro on all that ^^
15:25:38 <samccann> Would like y'all to poke around in the next day or so and let us know what you think. We don't really want to have to move major things around once the core branch pull happens, so would like to capture highlevel feedback asap
15:26:17 <DonNaro[m]> samccann: I think those changes are the root cause of this issue: https://github.com/ansible/ansible/issues/78760
15:26:48 <acozine> yeah, that looks like a TOC issue
15:27:04 <DonNaro[m]> at least 1 and 2 as the collection index and modules/plugins index moved to the specific guides
15:27:04 <samccann> ok I can look later. those tricky conf.py exclusions!
15:27:58 <acozine> hmm, wait a second
15:28:08 <DonNaro[m]> cheers. struggling to keep up as I'm double booked but I think there is still work with the toc and the need to setup redirects.
15:28:09 <acozine> I don't think the core docs should link to Collections
15:28:25 <samccann> core docs have a collection index with just builtin
15:28:34 <acozine> ah
15:29:24 <samccann> #info Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
15:29:24 <samccann> #info Help on issues always welcome :-)
15:29:25 <samccann> #info - if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.
15:29:26 <samccann> #topic doctools
15:29:37 <samccann> #info nightly docs build broken still.
15:30:03 <samccann> So I lost the plot on what's causing ^^.  Is this still to do with that final PR that fixes filter docs, or is it the requirements need to be updated? anyone remember??
15:32:09 <samccann> this is the most recent traceback - https://pastebin.com/Fh4NxqJ4
15:32:21 <samccann> (using antsibull 1.0.0 still in that jenkins build)
15:33:00 <felixfontein> well, the latest antsibull-docs release has a fix for that problem
15:33:09 <samccann> ok cool
15:33:22 <felixfontein> or should have, that is :)
15:33:30 <samccann> so we have two things driving a requirements update now - the core freeze deadline, and docs won't build w/o it ;-)
15:33:57 <felixfontein> yes... :)
15:34:01 <samccann> I did a local build yesterday w/ 1.4.0 and it worked so I think you are correct felixfontein
15:34:23 <felixfontein> at least we're pretty sure that the remaining docs-related core PRs won't break anything
15:34:36 <felixfontein> I've tested the latest antsibull-docs version with shertel's PR, and it works fine with it
15:34:48 <samccann> #action samccann to discuss requirements update w/ matt due to broken docs build etc
15:35:16 <samccann> ok so we could actually push in requirements updates before that merge? Like is there any reason to wait until after it merges if you've tested it?
15:35:56 <felixfontein> from my side yes (assuming that current devel branch likes working with antsibull-docs)
15:36:36 <samccann> yes as in wait or yes as in get a requirements PR up now?
15:37:16 <felixfontein> yes as in getting it up now
15:38:22 <samccann> #action samccann to get PR for requirements update ready
15:38:24 <samccann> coolness
15:39:31 <samccann> one other question I had for the hivemind. I saw last week that `community.aws` switched to using the docs CI work that generates a docsite in github etc.
15:40:16 <samccann> which is great! But the question  - the readme currently points to that generated docsite. Since this collection is part of the Ansible package, do we want the readme to point to the docsite instead? or not worth it incase acollection gets the boot in the future?
15:42:42 <felixfontein> hmm, I guess the question is what their own docsite is for
15:42:56 <samccann> (note - with old galaxy, that's the only way a user can find module docs)
15:42:59 <felixfontein> is it for the latest `main` branch? or for the latest release?
15:43:07 <samccann> ah good point
15:43:58 <felixfontein> the docsite says "Collection version 5.0.0-dev0"
15:44:23 <felixfontein> so I would assume it's the current `main` branch
15:44:25 <samccann> so the generated docsite seems to be main - https://ansible-collections.github.io/community.aws/branch/main/collections/community/aws/index.html#plugin-index
15:44:58 <felixfontein> in that case I would probably not link it from the README though, or at least not without some disclaimer, to avoid confusing users
15:46:07 <samccann> ok so the plot thickens
15:46:17 <samccann> https://galaxy.ansible.com/community/aws
15:46:40 <samccann> all the included content links are broken now, because they always pointed back to the main branch anyway
15:46:57 <samccann> (aka they were always not versioned correctly.
15:47:02 <felixfontein> hmm, the docsite link on galaxy isn't really helpful either
15:47:16 <felixfontein> (and I guess never really was)
15:47:26 <samccann> yeah I commented in the PR about that but maybe I'll open an issue instead w/ both of these items
15:48:23 <samccann> We have a few min left sooo.
15:48:26 <samccann> #topic Open Floor
15:48:41 <samccann> anyeone have anything docs related to talk about? Here's the time to bring it up.
15:48:46 <samccann> open to anything on your mind
15:49:11 <briantist> sorry was away
15:49:24 <briantist> on my collection, I link to all the docsites basically
15:49:38 <briantist> https://github.com/ansible-collections/community.hashi_vault/#collection-documentation
15:50:24 <felixfontein> I like that section :)
15:50:46 <samccann> ok I'll point to that from the issue I'll open up about this on `community.aws` thanks!
15:50:47 <briantist> I also recommended changing the galaxy.yml link to the devel docs on the public site: https://github.com/ansible-collections/community.aws/pull/1436#issuecomment-1244705473
15:51:05 <briantist> because that's what would match what they are seeing in galaxy
15:51:16 <acozine> yeah, that's a nice explanation and set of links
15:53:08 <briantist> for example: https://github.com/ansible-collections/community.hashi_vault/blob/main/galaxy.yml#L24
15:53:32 <samccann> cool thanks!
15:53:45 <samccann> anything else folks have in mind to chat about today?
15:54:48 <briantist> looks like the same suggestion should be made on `c.w` (and probbaly `a.w` I didn't check): https://github.com/ansible-collections/community.windows/blob/main/galaxy.yml#L16
15:56:25 <samccann> #action samccann to open issues on community.aws, community.windows, and possibly ansible.windows on using the correct links to module-level docs
15:56:47 <briantist> and probably `amazon.aws` too?
15:57:09 <samccann> in for a penny in for a pound!
15:57:26 <samccann> #action samcann also review amazon.aws for similar issue
15:57:40 <acozine> heh
15:57:46 <acozine> All the Collections
15:57:47 <briantist> thanks for that samccann it was a great find and something I've been overlooking
15:58:02 <samccann> :-)
15:58:58 <briantist> the AWS collections also have another option since they use stable branches
15:59:33 <briantist> in the galaxy.yml for those "not latest" branches, they could point to the docsites built by the GH workflows for those branches
15:59:41 <briantist> but I don't know how difficult that would be to manage
16:00:31 <briantist> I don't think they've been published yet, but the workflows are set up to do so
16:01:19 <briantist> or it could point to the tag docs builds, which will be built when the tag is pushed
16:01:21 <briantist> etc.
16:01:35 <briantist> it's probably TMI for right now 😅
16:01:43 <acozine> heh
16:01:57 <acozine> woopsie, next meeting calling me . . .
16:01:59 * acozine waves
16:02:03 <acozine> #unchair acozine
16:02:03 <zodbot> Current chairs: Don Naro briantist felixfontein samccann tremble
16:02:40 <samccann> lol thanks briantist
16:02:58 <samccann> meanwhile we are slightly past the hr so time to end the joy today
16:03:00 <samccann> #endmeeting