15:00:14 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:14 <zodbot> Meeting started Tue Sep 21 15:00:14 2021 UTC.
15:00:14 <zodbot> This meeting is logged and archived in a public location.
15:00:14 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:14 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:14 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:00:27 <samccann> #topic opening chatter
15:00:40 <samccann> So... this time... with feeling... who's around to talk the docs!
15:00:58 <ariordan[m]> I'm here.
15:01:03 * acozine waves
15:01:10 <Toshio[m]> Greetings :-)
15:01:15 <samccann> #chair ariordan
15:01:15 <zodbot> Current chairs: ariordan samccann
15:01:28 <felixfontein> hi o/
15:01:57 <samccann> andersson007_ dericcrago dmsimard gundalow tadeboro briantist cyberpear felixfontein mrproper[m] Xaroth you folks chatting docs today?
15:02:12 <ariordan[m]> #chair felixfontein
15:02:19 <gwmngilfen-work> Wait wait wait
15:02:38 <gwmngilfen-work> Do matrix accounts outnumber irc ones today? :)
15:03:06 <briantist> o/
15:03:10 <acozine> er, how would you tell? and does it matter?
15:03:26 <ariordan[m]> #chair acozine toshio
15:03:34 <gwmngilfen-work> It does not matter. But it is interesting to me
15:03:46 <ariordan[m]> #chair briantist
15:03:49 <gwmngilfen-work> I shall quit derailing :)
15:04:29 <ariordan[m]> #chair gwmngilfen
15:04:36 <samccann> heh
15:05:08 <felixfontein> #chair Toshio[m] gwmngilfen-work
15:05:11 <samccann> ok looks like a good crowd to get started. Agenda is at https://github.com/ansible/community/issues/579#issuecomment-920303632
15:05:18 <felixfontein> I think we need to use IRC usernames, otherwise meetbot won't correctly work
15:05:36 <samccann> hmm...
15:05:49 <samccann> #chair
15:05:49 <zodbot> Current chairs: ariordan samccann
15:06:08 <gwmngilfen-work> The bridge mostly translates them
15:06:13 <gwmngilfen-work> Mostly :)
15:06:16 <felixfontein> yes :)
15:06:21 <Toshio[m]> felixfontein: I was wondering about that....
15:06:29 <gwmngilfen-work> #chair @Gwmngilfen
15:06:32 <samccann> ok I'm a bit lost... I only see a couple of people listed in the chairs
15:06:41 <felixfontein> samccann: can you chair me?
15:06:48 <gwmngilfen-work> Well @ariordan isn't an op
15:06:58 <samccann> aaah good to know.
15:06:58 * Toshio[m] switches to his irccloud tab for this meeting
15:07:03 <gwmngilfen-work> #chair gwmngilfen-work
15:07:06 <samccann> #action samccann to get ariordan ops rights
15:07:17 <samccann> #chair acozine felixfontein
15:07:17 <zodbot> Current chairs: acozine ariordan felixfontein samccann
15:07:33 <abadger1999> o/
15:07:33 <felixfontein> #chair gwmngilfen-work Toshio[m] abadger1999 ariordan[m]
15:07:33 <zodbot> Current chairs: Toshio[m] abadger1999 acozine ariordan ariordan[m] felixfontein gwmngilfen-work samccann
15:07:43 <gwmngilfen-work> Pfft
15:07:46 <gwmngilfen-work> :)
15:07:57 <felixfontein> zodbot - matrix interaction needs some more work :)
15:08:11 <acozine> doppelgangers!
15:08:16 <gwmngilfen-work> With the fedora matrix rollout progressing, that may come at some point :)
15:08:16 <samccann> #chair ok so the only real problem was I'd asked ariordan to handle chairs and she doesn't have the correct rights yet, right?
15:08:16 <zodbot> Current chairs: I'd Toshio[m] abadger1999 acozine and ariordan ariordan[m] asked chairs correct doesn't felixfontein gwmngilfen-work handle have ok only problem real right? rights samccann she so the to was yet
15:08:20 <felixfontein> #chair briantist
15:08:20 <zodbot> Current chairs: I'd Toshio[m] abadger1999 acozine and ariordan ariordan[m] asked briantist chairs correct doesn't felixfontein gwmngilfen-work handle have ok only problem real right? rights samccann she so the to was yet
15:08:49 * gwmngilfen-work pulls rank
15:08:51 <acozine> okay, that's just weird
15:08:54 <felixfontein> samccann: the problem is that you used ariordan[m]'s Matrix name, not IRC name
15:08:56 <samccann> omgosh what just happened. lol I chaired a sentence!
15:08:58 <felixfontein> when giving #chair
15:09:09 <felixfontein> so ariordan[m] couldn't chair anyone
15:09:14 <gwmngilfen-work> hmm, we have never had this issue n a wed
15:09:18 <gwmngilfen-work> *on
15:09:40 <felixfontein> #unwhair I'd and asked chairs correct doesn't handle have ok only problem real right? rights she so the to was yet
15:09:44 <felixfontein> #unchair I'd and asked chairs correct doesn't handle have ok only problem real right? rights she so the to was yet
15:09:44 <zodbot> Current chairs: Toshio[m] abadger1999 acozine ariordan ariordan[m] briantist felixfontein gwmngilfen-work samccann
15:09:45 <samccann> this is my first attempt to do this in matrix. Seems I have a few things to learn
15:10:00 <samccann> thanks felixfontein !
15:10:29 <samccann> ok.. I think we might be ready to cover the current topic of action item reviews
15:10:33 <felixfontein> well, without trying it we don't really notice all the little problems :)
15:10:39 <acozine> word salad fun
15:10:45 <gwmngilfen-work> ah, presumably because felixfontein runs the meetings on a wed
15:11:05 <felixfontein> gwmngilfen-work: probably :)
15:11:16 <samccann> We didn't have any new action items last week and we were mostly caught up except for a couple of items
15:11:26 <samccann> #info still need to followup on CI testing with Sphinx 4
15:11:40 <felixfontein> the attributes dispute seems to be resolved (by authority)
15:12:00 <samccann> #info still need to reword the intro to collection modules so they don't suggest a user has to install the collection (it's already in Ansible)
15:12:16 <samccann> Any other action item reviews before we get into Higher Authority topics? ;-)
15:12:40 <acozine> samccann: is there an issue for `reword the intro to collection modules` thing?
15:13:06 <samccann> acozine: no I don't think so unless you check directly in antsibull repo.
15:14:01 <samccann> #action samccann ariordan to create issue to update wording on antsibull for collection module boilerplate text
15:14:28 <abadger1999> I haven't noticed one in the antsibull repo
15:15:08 <samccann> ok we'll create one and then one of us can do the PR directly since it's wordsmithing fun
15:15:17 <ariordan[m]> cyb-clock-clone says we are 15 minutes into the meeting
15:15:26 <samccann> :-)
15:15:56 <samccann> #topic core-2.12 docs needs
15:16:08 <samccann> #info we are tracking 2.12 docs needs with https://github.com/ansible/ansible/issues/75664
15:16:26 <samccann> #info if you see anything missing, please add as a comment to that issue
15:16:38 <samccann> that's just for the meeting minutes. now onto the real topic
15:16:48 <samccann> #info new module atttributes
15:16:51 <samccann> dag nammit
15:16:55 <samccann> #uninfo
15:17:07 <samccann> #topic New module attributes
15:17:52 <samccann> #info background - core supports displaying a batch of 13 or more attributes. See https://github.com/ansible/ansible/issues/75164 for the debate on the docs side
15:18:13 <samccann> #info after much deliberation and resorting to a Higher Authority (tm) the decision is to display all the attributes.
15:18:47 <samccann> #info we need to determine next if we can do this in a table or if it must be some kind of list. The problem is - each attribute can have 3-6 fields.
15:18:56 <samccann> So that's where we are now.
15:19:10 <felixfontein> also the attributes feature is still in flux - see https://github.com/ansible/ansible/pull/75619
15:19:16 <felixfontein> I hope it gets finalized soon
15:19:44 <samccann> #info https://github.com/ansible/ansible/pull/75619 is the next step on this in core and still in flux.
15:19:49 <felixfontein> the current version has some new backwards compatibility problems (https://github.com/ansible/ansible/pull/75619#discussion_r712698799) which would require another set of backports if they are kept as-is
15:19:58 <abadger1999> Note that a list can be made to look like a table via CSS if needed.
15:20:11 <samccann> I think for us, we need to look at what the 3-6 fields are and can they be combined in some what such that we can have a table
15:21:15 <felixfontein> I think description, content, and the special-purpose fields can be combined into one table cell
15:21:25 <felixfontein> s/content/details/
15:22:11 <samccann> #info also, from a usability perspective (mobile apps, etc) - tables are frowned upon
15:22:13 <samccann> yeah my conundrum right now - we already have pretty intense tables in plugin docs for the parameters table. Do we continue that with an attributes table. or do we go to a list as it is more mobile friendly.  And possibly screen-reader friendly? does anyone know about the accessibility impact of table vs list?
15:22:16 <felixfontein> I'll try to whip together a PR for a table once we get to the point that the feature stabilizes in core
15:22:46 <samccann> That would be great felixfontein thanks!
15:22:55 <abadger1999> lists are definitely preferred over tables for screenreaders.
15:23:09 <felixfontein> if we use a specially formatted list, conversion via CSS should be easy to do
15:23:28 <abadger1999> I don't know the details of why but it is the guidance I've received for yeras
15:24:02 <samccann> can you explain that a bit more on the CSS? Does it mean it would be a table on wide screens (laptops) and a list on small screens (mobile)?
15:24:27 <samccann> abadger1999: yeah I've heard that as well
15:24:55 <samccann> so this may be a situation where we should start following accessibility guidelines since it's something brand new and we have the chance to do it right
15:24:59 <abadger1999> You can look at ./dev_guide/collections_galaxy_meta.rst   for an example of how to create a list and assign it a specific CSS class so it can be formatted how we want
15:25:05 <felixfontein> samccann: yes it means that. you can use `display: table` and friends to show something as a table
15:25:32 <gwmngilfen-work> +1 for accessibility from someone who has to do zero of the work :)
15:25:37 <felixfontein> with plain HTML + CSS it's easy to do, with sphinx inbetween it might be a bit more tricky (if several things should go into one cell)
15:26:17 <samccann> #info look at ./dev_guide/collections_galaxy_meta.rst   for an example of how to create a list and assign it a specific CSS class so it can be formatted how we want
15:26:31 <abadger1999> Oooh, actually, dev_guide/collections_galaxy_meta.rst probably produces an html table... it's only the rst that is in list format.
15:26:51 <samccann> #uninfo
15:27:01 * samccann ponders if uninfo is the right command
15:27:06 <abadger1999> #undo
15:27:06 <zodbot> Removing item from minutes: INFO by samccann at 15:26:17 : look at ./dev_guide/collections_galaxy_meta.rst   for an example of how to create a list and assign it a specific CSS class so it can be formatted how we want
15:27:15 * samccann finds out she's wrong
15:27:18 <samccann> thanks!
15:27:22 <felixfontein> it's probably some sphinx directive which renders that as a table, it's definitely not CSS
15:27:47 <felixfontein> `.. list-table::` says a lot :)
15:27:50 <abadger1999> #info  dev_guide/collections_galaxy_meta.rst  has an example of how to add a CSS class in rst and also of using an rst list to output an html table
15:27:56 <samccann> ok so I'm leaning toward we don't use a table anyway for accessibility reasons. Should we VOTE on this, or do we want to see examples first?
15:28:33 <felixfontein> it's probably better to try first and see how it looks
15:28:43 <samccann> a list would be more accessible and more mobile-friendly I think. Two birds, one stone
15:28:46 <samccann> ok
15:29:01 <samccann> #action samccann to mock up the attributes as a list
15:29:17 <samccann> Anything else on this before we move to the next topic?
15:30:13 <ariordan[m]> cyb-clock-clone says we are 30 minutes into the meeting
15:30:21 <samccann> ok movin on!
15:30:29 <samccann> #topic ssh doc problem
15:30:35 <samccann> #info see https://github.com/ansible/ansible/pull/73708
15:31:08 <samccann> There was talk at one point about having that PR reverted, but I lost track of where that is.
15:31:50 <abadger1999> nitzmahone had said he thought it should be reverted but last week (I think) sivel said that the core team leadersihp had decided to keep it in
15:32:29 <abadger1999> When I had talked to nitzmahone, I had mentioned that it did fix some problems and that a less intrusive change would be to change from using the internal variable into using the command line name.
15:32:31 <samccann> so does that mean we change something in antsibull-docs now? I'm not sure why it broke in the first place really
15:32:40 <abadger1999> But that wasn't done.
15:33:14 <abadger1999> They have added a second field that is optional and when present is the command line name.
15:33:24 <felixfontein> samccann: I already merged a PR which prevents the error message
15:33:28 <felixfontein> (yesterday night)
15:33:37 <samccann> ok cool!
15:33:46 <samccann> #info felixfontein merged a PR which prevents the error message
15:33:47 <abadger1999> They aren't going to make that mandatory and fill in the information for all the fields for 2.12
15:33:48 <felixfontein> I'll probably try a PR next which adds that information to the output, but I'll probably look at the attributes first
15:34:01 <abadger1999> That's the status of the data side.
15:34:10 <samccann> ok thanks abadger1999
15:34:47 <samccann> felixfontein: so we should still keep this item on the agenda until you get a chance to work on the next PR that adds that info to the output?
15:35:10 <felixfontein> samccann: I think that's a good idea
15:35:11 <samccann> #info still needs additional work/PR to add the new info to the output for the ssh plugin
15:36:10 <samccann> anything else on this topic before we shift to another topic?
15:37:07 <samccann> ok movin on
15:37:17 <samccann> #topic expand/collapse in sphinx
15:37:47 <samccann> #info would be nice to have this capability so we can display the new attributes in collapsed state.
15:38:10 <samccann> #info see https://github.com/ansible-community/antsibull/pull/303#issuecomment-918345118
15:38:50 <samccann> #info a test PR for this is at https://github.com/ansible/ansible/pull/75695 but has CI problems
15:39:08 <samccann> I'm not sure about those CI problems but I haven't gone back to it in over a week.
15:40:00 <samccann> I fixed the first problem (sphinx_design) but the other two remain. rstcheck complains about the new directive, and that pep8 problem.
15:40:08 <felixfontein> samccann: the sanity issue with rstcheck is that rstcheck doesn't know about the new directive that's used
15:40:31 <samccann> yeah not sure what we can do about that, though.
15:40:53 <samccann> we don't control rstcheck. I don't know if there's some 'local' way to extend it so it can learn about the new directive or not
15:40:55 <felixfontein> I think the sanity test can be extended to accept that directive, but someone would have to implement that :)
15:41:03 <felixfontein> we do control the sanity test, though
15:41:10 <felixfontein> (or well, mattclay does ;) )
15:41:13 <acozine> yeah, those CI failures are what prevents the upgrade of CI to the latest Sphinx
15:41:45 <acozine> so instead of CI preventing the change getting merged, the merging of the change is preventing updating CI to the latest
15:42:12 <samccann> sorry not following that acozine
15:42:27 <felixfontein> https://github.com/ansible/ansible/blob/devel/test/sanity/code-smell/rstcheck.py could be rewritten to use rstcheck as a library, and then one can use the same code as in https://github.com/ansible-community/antsibull/pull/281 to teach it about that directive
15:42:52 <abadger1999> If your project has custom roles and directives, you can specify them in the local configuration of the project. rstcheck looks for a file .rstcheck.cfg in the directory or ancestor directory of the file it is checking.
15:43:04 <acozine> ooh, that sounds like a great approach
15:43:07 <felixfontein> ah. that might be even easier :)
15:43:17 <abadger1999> [rstcheck]
15:43:17 <abadger1999> ignore_directives=one,two,three
15:43:22 <samccann> felixfontein: sounds like a lot of code changes for the final week before freeze. I wonder if this expand/collapse has to wait til 2.13
15:43:36 <abadger1999> That's from the rstcheck documentation
15:43:45 <samccann> oh that's good to know abadger1999
15:43:55 <felixfontein> samccann: since the rstcheck test is ansible-repo specific, I think it could also be backported after the freeze. if that's needed and the config file method doesn't work.
15:44:11 <samccann> #info we can extend irstcheck to ignore the new directives.
15:44:23 <samccann> your project has custom roles and directives, you can specify them in the local configuration of the project. rstcheck looks for a file .rstcheck.cfg in the directory or ancestor directory of the file it is checking.#info
15:44:35 <samccann> oh carp again.
15:44:42 <abadger1999> Hehe
15:44:48 <samccann> #action samccann go read rst check docs for how to do this
15:45:11 <samccann> that's very helpful everyone!
15:45:25 <samccann> anything else before we shift to next topic?
15:45:53 <ariordan[m]> cyb-clock-clone says we are 45 minutes into the meeting
15:46:23 <samccann> #topic Ansible 5 docs needs
15:47:02 <samccann> I wanted to cover this one quickly. Other than the usual batch of work we do for every Ansible 5 release (porting guides, etc) - is there anything on Ansible 5 that we need to get in place that we haven't covered here today?
15:47:27 <samccann> I'd like to create a checklist issue for Ansible 5 but wanted to see if there were new/unusual items we needed on it
15:47:47 <felixfontein> I think the main issues for Ansible 5 are the same ones as for ansible-core 2.12. at least the ones I'm aware of :)
15:48:07 <samccann> ok cool. Was hoping that was the answer but wanted to check
15:49:08 <samccann> ok with that, might just open the fllor
15:49:13 * samccann must learn to spell!
15:49:19 <samccann> #topic Open Floor
15:49:48 <samccann> This is the time to bring up anything you want docs related. Favorite PR or issue that's not getting attention, other docs ideas or problems??
15:50:40 <samccann> briantist: I think you linked to an issue in the DaWGs agenda. did you want to talk about it here?
15:50:52 <briantist> did I? 🤔
15:51:25 * samccann goes to check
15:51:42 <briantist> ah it was a mention, that was the issue where I started jotting down notes and such for docs build
15:51:55 <briantist> https://github.com/ansible-collections/community.hashi_vault/issues/138
15:52:03 <samccann> ah ok. Any updates to share with that?
15:52:46 <briantist> some suggestions in there from webknjaz about using RTD rather than Surge for publishing
15:53:05 <briantist> but I don't have the bandwidth to look into that for now, and it seems like it may warrant some changes to antsibull as well? I'm not entirely sure
15:53:11 <briantist> otherwise no particular updates
15:53:14 <samccann> cool.
15:53:51 <samccann> ok cool, thanks for sharing the details so far
15:54:06 <samccann> Anyone else have an open floor item to discuss?
15:55:22 <samccann> i have more of a quick question (not docs related)
15:55:37 <acozine> nothing from me
15:55:49 <felixfontein> nothing from me either
15:56:01 <samccann> ariordan: pointed out that docker is going fee based soon and I know `ansible-test` uses docker. Do we know if that's going to stay that way or if they will change it?
15:56:39 <samccann> ...or if there are already containter-based options other than docker and we should change the docs to start using those other options instead of `ansible-test sanity --docker` ?
15:56:56 <felixfontein> it depends on which parts of Docker you talk about. the docker engine / CLI tools are open source and won't cost money
15:57:40 <samccann> well I guess ^^ is my question then. Can a user continue to do that ansible-test command? or will they have to pay?
15:57:41 <felixfontein> there might be costs involved with some Docker desktop software I think (which you might need for macOS / Windows?), and for Docker Hub
15:57:59 <felixfontein> since ansible-test uses Docker images from quay.io by default, this shouldn't be a problem
15:58:27 <felixfontein> no idea how the situation is on macOS though, because there Docker needs to do more heavy lifting than on Linux
15:58:30 <samccann> ok cool thanks! I wasn't sure and didn't want to leave the docs pointing to something that might cost $$
15:59:01 <felixfontein> though ansible-test's `--docker` also supports podman, and its support gets better all the time
15:59:02 <samccann> I don't have anything else... anyone else have a list minute thought before we close the meeting?
16:00:02 <samccann> ah so even tho it's `--docker` in the command, it can use podman under the covers so to speak? good to know
16:00:59 <felixfontein> yes. though it might be problematic with ansible-core 2.11 and earlier; it definitely got improved for ansible-core 2.12
16:01:10 <ariordan[m]> cyb-clock-clone says we are 60 minutes into the meeting
16:01:33 <samccann> cool
16:01:39 <samccann> and that's a wrap folks!
16:01:42 <samccann> #endmeeting