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