15:00:43 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:43 <zodbot> Meeting started Tue Jul 26 15:00:43 2022 UTC.
15:00:43 <zodbot> This meeting is logged and archived in a public location.
15:00:43 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:43 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:43 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:00:44 <samccann> #topic Opening Chatter
15:00:54 <samccann> @room who's around to talk docs today?
15:01:23 <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:01:51 <acozine> o/
15:02:02 <samccann> #chair acozine
15:02:02 <zodbot> Current chairs: acozine samccann
15:02:04 <samccann> welcome!
15:02:28 <acozine> quiet day today
15:02:28 <samccann> briantist: felixfontein around for docs today?
15:02:30 <acozine> summer, I guess
15:02:35 <felixfontein> o/
15:02:39 <briantist> o/
15:02:41 * acozine can't really complain as she has been out the last couple of weeks
15:02:50 <briantist> only half here once again, sorry
15:02:50 <felixfontein> :)
15:02:50 <samccann> #chair felixfontein  briantist
15:02:50 <zodbot> Current chairs: acozine briantist felixfontein samccann
15:02:54 <felixfontein> today I'm actually around
15:03:00 <felixfontein> even though my internet connection is pretty crappy
15:03:04 <samccann> we'll take 1/2 briantist !!
15:03:14 <briantist> 😊
15:03:41 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1189351649
15:03:57 <samccann> #topic Documentation updates
15:04:08 <samccann> #info User guide is being split into multiple guides. See https://docs.ansible.com/ansible/devel/index.html for current status. More to come.
15:04:55 <samccann> right now it's focused on moving files around into indiividual guides so it's easier to find. Inventory is next I think but Don Naro is doing the work (and on pto this week so let's assign him all the action items!)
15:05:09 <acozine> heh
15:05:24 <felixfontein> hehe :)
15:05:55 * acozine is now half-gone, restarting a production server
15:06:04 <felixfontein> so which week was it you're on pto samccann? ;)
15:06:19 <samccann> I think it was 3 weeks ago?
15:06:33 <felixfontein> darn, we missed the chance...
15:06:40 <samccann> but gonna snag another at start of Sept I think.
15:06:41 <samccann> hahah
15:07:05 <samccann> #info - 2.3 docs audit - most pages 1x1 map to latest. See https://hackmd.io/0B7n-FUySF6MB3CQeaqUkA#23-Audit for details.
15:07:16 <samccann> So ^^ is in preparation for the Great Redirect
15:07:32 <samccann> as in redirecting most 2.3 docs traffic to latest.
15:07:38 <felixfontein> cool!
15:07:48 <samccann> alas, I still can't get the redirect for 'not an empty referrer' to work
15:08:09 <samccann> RewriteCond %{HTTP_REFERER} !^$
15:08:46 <samccann> anyone have a guess on what might be wrong there?
15:09:27 <felixfontein> no idea, but how about something like `RewriteCond %{HTTP_REFERER} ^.` instead?
15:09:42 <samccann> what does that one do?
15:10:00 <felixfontein> basically it checks that there is any character at the beginning of the referrer
15:10:16 <samccann> worth a try for sure, thanks
15:10:35 <felixfontein> (assuming that's how the syntax of the rest of the line actually work... I can only talk about the regex :) )
15:10:43 <samccann> #action samccann to try RewriteCond %{HTTP_REFERER} ^. for referrer problem with 2.3
15:11:31 <samccann> if I can't get it working, I may just go back to the archive site idea. This one has had me stumped for days
15:11:48 <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:12:23 <samccann> just a reminder we have a team of volunteer community-writers happy to help out with docs edits etc. Open to anything ansible-related on github
15:13:16 <samccann> #topic DocTools
15:13:30 <samccann> #info boolean yes/no vs true/false etc vote happening at https://github.com/ansible-community/community-topics/issues/116 . Get your vote in before 8/03.
15:14:13 <samccann> that's gotten quite a lot of votes on it so far!  Though i don't know how many are steering committee votes
15:14:33 <felixfontein> right now a large majority seems to favor true/false, though from the SC there's 1/3 for yes/no from the ones who voted so far
15:14:44 <felixfontein> (assuming I didn't screw up the counting)
15:15:05 <samccann> coolness
15:15:45 <samccann> any other tooling updates? on antsibull-docs or briantist's CI docs testing fun?
15:15:57 <briantist> ah crap I got pulled away
15:16:00 <briantist> I do have one update
15:16:24 <felixfontein> nothing fancy from my side... I've tested bcoca's docs refactor PR and added some comments about changes I noticed
15:16:40 <briantist> both of the windows collections (`community.windows` and `ansible.windows`) are now using the github-docs-build tooling 🎉
15:17:08 <samccann> #info both of the windows collections (`community.windows` and `ansible.windows`) are now using the github-docs-build tooling
15:17:09 <samccann> cool!
15:17:09 * acozine is back
15:17:10 <briantist> thanks to Jordan and Nitz for reviewing and setting up GH-pages and such
15:17:25 <felixfontein> (besides that there's a PR with licensing details... definitely not very interesting to users)
15:17:38 <samccann> felixfontein: what does bcoca's refactor do? Anything we should test visually on the test site?
15:17:39 <acozine> briantist: ooh, the docs-build tools are expanding their territory!
15:17:41 <felixfontein> ah, that's cool news!
15:18:00 <felixfontein> samccann: it should not have visible output, I think, though right now it does have
15:18:31 <felixfontein> though at least one thing seems to be actually fixing something that was broken before (but nobody really noticed)
15:18:31 <samccann> ok thanks
15:19:17 <felixfontein> my summary is https://github.com/ansible/ansible/pull/77719#issuecomment-1195253853
15:19:28 <samccann> so on the topic of docs-built tools - I still need to open issues on a zillion collections to get folks cleaning up their docs warnings etc. Last I checked we are over 1100!
15:19:52 <felixfontein> the bug it fixes is that for example https://docs.ansible.com/ansible/devel/collections/ansible/builtin/csvfile_lookup.html#parameter-delimiter shows `\\t` instead of `\t`
15:20:37 <samccann> cool
15:20:41 <briantist> After enabling, we did find a few (very few) small errors/warnings that have since been fixed, so that's a little bit
15:20:47 <briantist> (int he windows collections I mean)
15:21:41 <samccann> thanks briantist  I may reach out this week for help on how to run tests 'locally'. I know I've gotten it working in the past. But I want to be able to put to 'use this docs CI testing approach, or run foo locally' on the issues I eventually open.
15:22:14 <samccann> so collection owners can verify it's all clean.
15:22:15 <briantist> IIRC your hackmd instructions for running locally are accurate
15:22:28 <samccann> and I also want to 'get in the habit' of running it on proposed new collections to catch em before they come in so to speak
15:22:34 <samccann> cool thanks
15:23:05 <briantist> rather than thinking of it as adopting the CI process locally, really the CI process is built around the "local" procedure that Felix introduced with `antsibull-docs sphinx-init` :)
15:23:15 <acozine> felixfontein: in your comment on PR 77719, I'm confused by the disappearing filter docs
15:24:14 <felixfontein> acozine: that looks like a bug. I find it strange since the disappearing filter is documented in the same way as other filters in the same collection
15:24:20 <felixfontein> (filters also disappear in other collections)
15:24:25 <acozine> is this only at the command line? or in the published docs as well?
15:25:01 <acozine> it certainly "smells" like a bug, but a very strange one
15:26:25 <felixfontein> it's both
15:27:27 <felixfontein> i.e. both `ansible-doc --type filter --list` and `ansible-doc --metadata-dump`
15:28:32 <acozine> oof
15:28:40 <acozine> that feels like a big blocker to me
15:30:19 <samccann> do we need to put in a blocking comment to that effect?
15:31:11 <acozine> I'm happy to add a comment; not sure how much attention anyone will pay
15:31:28 <samccann> #info for https://github.com/ansible/ansible/pull/77719#issuecomment-1195253853 - filter docs don't work for ansible-doc --type filter --list` and `ansible-doc --metadata-dump`  or on the docsite
15:31:43 <samccann> yes please do acozine
15:32:09 <felixfontein> most filters work, it's just some that do not
15:32:23 <samccann> #info most filters work, but some do not
15:33:38 <acozine> done, and it appears right below felix's comment, so it should be easy to follow the logic there
15:33:57 <samccann> cool thanks
15:34:02 <samccann> #topic Open Floor
15:34:19 <samccann> Here's the time anyone can bring up a docs-related topic..pr/..issue etc
15:35:59 <samccann> or perhaps it's time for Docs Comedy Hour!
15:36:09 <samccann> how many RST files does it take to heat up a room?
15:37:25 <samccann> huh no takers eh?
15:38:12 <samccann> we might have lost peeps to $DAYJOB
15:38:12 <acozine> sorry
15:38:13 <samccann> anyone else have anything to add before we end the meeting?
15:38:20 <bcoca> felixfontein: have you tested using the collection as a param?
15:38:27 <samccann> no worries. We covered everything and doesn't seem like anyone else has a tidbit to add
15:38:29 <felixfontein> bcoca: yes
15:38:38 <bcoca> i updated pr with response, pretty sure its basename/fqcn issue
15:38:46 <samccann> !EXCEPT BCOCA!
15:38:47 <samccann> heh
15:38:56 <acozine> between the construction here at home and the server going down at work, I'm a little distracted
15:39:05 <acozine> bcoca: oh, interesting
15:39:55 <bcoca> i'll have to add a test and a fix , wont merge w/o solving that issue, 1,2 are 'fixes' 3 is known issue but not sure how to work around it
15:40:11 <acozine> ah, so any filter name that exists in multiple collections (like `split`) gets dropped . . . that makes sense
15:40:30 <acozine> I mean, it needs to be fixed, but at least there's a reasonable explanation for which ones get dropped
15:40:31 <bcoca> well, gets dropped from 'list' but you can still access the docs
15:40:36 <bcoca> yep
15:40:43 <bcoca> again, will fix
15:40:55 <bcoca> ansible.builtin.split is not 'only split'
15:40:57 <acozine> and not just "every 17th filter we just dump in a black hole"
15:41:00 <acozine> excellent, thanks!
15:41:10 <bcoca> acozine: then it woudl be a loop issue
15:41:25 <felixfontein> yep, it seems to be basename/FQCN issue
15:41:29 <acozine> heh
15:41:34 <bcoca> though i would try  to either match prime numbers or fibonacci sequence, every 17 seems boring
15:41:59 <samccann> heh
15:42:46 <samccann> anything else before we close shop today
15:42:57 <acozine> not from me
15:43:33 <felixfontein> not from me either
15:43:41 <samccann> #endmeeting