15:01:12 <acozine> #startmeeting Documentation Working Group aka DaWGs
15:01:12 <zodbot> Meeting started Tue Aug 31 15:01:12 2021 UTC.
15:01:12 <zodbot> This meeting is logged and archived in a public location.
15:01:12 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:12 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:12 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:12 <samccann> wooo hooo!!
15:01:18 <acozine> #topic opening chatter
15:01:22 <acozine> #chair samccann
15:01:22 <zodbot> Current chairs: acozine samccann
15:01:28 <tadeboro> o/
15:01:30 <acozine> who else is around?
15:01:33 <acozine> #chair tadeboro
15:01:33 <zodbot> Current chairs: acozine samccann tadeboro
15:01:34 <samccann> oh... we seldom use idea... must... experiment...!!
15:01:44 <acozine> heh
15:01:52 <acozine> I'd never even noticed it!
15:01:56 <samccann> #idea ... what does the idea hashtag do in the meeting minutes???
15:02:01 <samccann> there... we can see later
15:02:45 <acozine> abadger1999: andersson007_ dericcrago dmsimard gundalow ariordan briantist cyberpear felixfontein mrproper[m] Xaroth you folks chatting docs today?
15:02:53 <acozine> lmodemal[m] has a conflict, I know
15:03:02 <briantist> o/
15:03:12 <gundalow> Yes
15:03:16 <ariordan> Yes
15:03:22 <acozine> official agenda begins with https://github.com/ansible/community/issues/579#issuecomment-904852018
15:03:29 <acozine> #chair briantist gundalow ariordan
15:03:29 <zodbot> Current chairs: acozine ariordan briantist gundalow samccann tadeboro
15:03:31 <gwmngilfen-work> 👋
15:03:35 <acozine> #chair gwmngilfen-work
15:03:35 <zodbot> Current chairs: acozine ariordan briantist gundalow gwmngilfen-work samccann tadeboro
15:03:40 <Xaroth> I'm around-ish
15:03:42 <acozine> ooh, fancy emoji!
15:03:48 <acozine> Xaroth: cool, do you want to be furniture?
15:03:49 <Xaroth> need to have a resignation talk first though.
15:03:51 <felixfontein> o/
15:03:56 <Xaroth> I'm always furniture.
15:03:57 <acozine> #chair felixfontein
15:03:57 <zodbot> Current chairs: acozine ariordan briantist felixfontein gundalow gwmngilfen-work samccann tadeboro
15:04:00 <acozine> heh
15:04:04 <acozine> #chair Xaroth
15:04:04 <zodbot> Current chairs: Xaroth acozine ariordan briantist felixfontein gundalow gwmngilfen-work samccann tadeboro
15:04:43 <acozine> as a reminder, I will be on vacation for the next two DaWGs meetings
15:05:02 <felixfontein> enjoy your vacation!
15:05:09 <acozine> when I return on Sept 21 I will be on the community side
15:05:21 <acozine> thanks!
15:05:53 <acozine> okay, our first agenda item may be a bit painful
15:05:59 <acozine> #topic action item review
15:06:06 <samccann> heh
15:06:37 <acozine> recent action items:
15:07:03 <acozine> Add `deciding how attributes should be displayed` to the agenda
15:07:05 <acozine> done
15:07:41 <acozine> Summarize in a HackMD the main questions, challenges, and solutions related to displaying attributes
15:07:54 <acozine> here's how far I got: https://hackmd.io/Fy9kYQXrTHSE4ceLZph9ew
15:08:32 <acozine> Open an issue on the ansible sphinx theme asking for expand/collapse
15:08:48 <acozine> the box is checked . . . samccann do you have a link to hte issue?
15:09:14 <samccann> I added more on the attributes to this hackmd - https://hackmd.io/R71WLQjPQOa-Ze0Cg97V7A
15:09:20 <samccann> and linked to it from the issue
15:09:22 <felixfontein> for expand/collapse, webknjaz listed some plugins: https://github.com/ansible-community/antsibull/pull/303#issuecomment-905391511
15:09:59 <felixfontein> and for attributes, there's a compatibility PR for stable-2.11 (which can be backported further once merged): https://github.com/ansible/ansible/pull/75563
15:10:12 <acozine> ooh, a PR and even some existing plugins! that's awesome
15:10:32 <felixfontein> someone has to try how the existing plugins look with the theme
15:10:37 <samccann> #info details on attributes - https://hackmd.io/R71WLQjPQOa-Ze0Cg97V7A  and PR - https://github.com/ansible/ansible/pull/75563
15:11:05 <samccann> #action samccann to test out https://github.com/ansible/ansible/pull/75563 to see how it looks
15:11:40 <samccann> #info expand/collapse on the ansible theme has some suggestions at https://github.com/ansible-community/antsibull/pull/303#issuecomment-905391511
15:11:40 <felixfontein> https://sphinx-design.readthedocs.io/en/furo-theme/dropdowns.html looks pretty nice; https://sphinx-toolbox.readthedocs.io/en/stable/extensions/collapse.html#directive-collapse would need some CSS
15:12:02 <felixfontein> (if it should look different than a plain <details>)
15:12:40 <acozine> I would vote for the one that doesn't require additional CCS - maintaining CCS gives me nightmares
15:12:45 <felixfontein> :+1:
15:13:08 <felixfontein> assuming it doesn't look like shit with our theme (which I don't think it will, but someone should try it out first)
15:13:28 <acozine> yeah
15:13:58 <acozine> what would it take to get a branch with that work that we could publish to the test site?
15:14:13 <felixfontein> I think not much
15:14:33 <felixfontein> basically create a branch, mention the plugin in requirements.txt and sphinx config, and use the directive somewhere
15:14:49 <samccann> yeah what were we considering using the directive on?
15:14:56 <acozine> looooooonnnnngggg pages
15:15:07 * acozine tries to remember a specific example
15:15:11 <acozine> the filters page is huge
15:15:14 <samccann> so not on like module docs, but some of the rst pages with long examples?
15:15:35 <acozine> that's my recollection
15:15:47 * acozine looks for the minutes
15:15:55 <samccann> heh  yeah looking there as well
15:16:17 <acozine> yeah, we were talking about creating the new "patternbook" of examples
15:16:31 <acozine> and thinking it would be a very, very long page
15:16:55 <samccann> ah ok yeah for the future examples pages.
15:17:02 <acozine> specifically we were talking about expand/collapse for code examples
15:18:19 <samccann> ok I can give these existing extensions a try and see what they look like
15:18:27 <acozine> excellent
15:18:58 <samccann> #action samccann to test out the expand/collapse extensions listed in https://github.com/ansible-community/antsibull/pull/303#issuecomment-905391511 to see how they display
15:19:37 <acozine> we also had an action item for "create a topic issue for the community WG on community-contributed examples"
15:20:14 <acozine> it's checked, samccann do you have a link handy?
15:20:17 <samccann> yeah that was done and discussed... lemme dig up the issue
15:20:41 <felixfontein> https://github.com/ansible-community/community-topics/issues/39
15:20:45 <samccann> https://github.com/ansible-community/community-topics/issues/39#issuecomment-906133762
15:20:53 <samccann> heh ok felixfontein's is better.
15:21:37 <samccann> something that comes to mind - what kinds of examples are we looking for?
15:21:56 <acozine> first-round request is for templating examples
15:22:21 <acozine> preferable "self-contained" ones - so you can see the data inputs, the expressions, and the outputs
15:22:27 <acozine> and see how it all fits together
15:23:10 <acozine> that one example was a short playbook with a `vars:` section for the data, a task, and a `debug` statement
15:23:18 <acozine> below that, the output
15:23:52 <samccann> brb
15:24:15 <acozine> woopsie, it's almost half past the hour
15:24:49 <acozine> okay, last check-in on action items:  "create a PR to update the Debian install instructions" is done - PR is https://github.com/ansible/ansible/pull/75571/files
15:25:03 <acozine> I'll publish it to the testing site quickly, should be able to merge it today
15:25:10 <acozine> ohhhh
15:25:16 <acozine> one older one I do have an update on
15:25:24 <acozine> Sphinx upgrades in CI
15:26:14 <acozine> #info we were able to update CI to use Sphinx 3.5.4 but Sphinx 4.x generates errors
15:27:05 <acozine> #info on Sphinx 4.x we get the `1 validation error for ModuleDocSchema\ndoc -> attributes\n  extra fields not permitted ` warnings
15:27:53 <felixfontein> hmm, how exactly do these warnings look?
15:28:03 <acozine> those are triggered by the attributes work, I think
15:28:06 <gundalow> hum, is that from Sphinx, or ansible-test's validate modules?
15:28:16 <felixfontein> sounds like antsibull
15:28:21 <felixfontein> I'm wondering how this results in sphinx warnings
15:28:35 <acozine> yeah, it's antisbull
15:28:51 <acozine> because the current schema doesn't include the extra fields
15:29:08 <acozine> https://www.irccloud.com/pastebin/eIT0SdYX/Sphinx%204%20error%20messages
15:29:31 <felixfontein> but that should be a problem for either both sphinx versions, or none
15:29:50 <samccann> back
15:29:56 <felixfontein> the interesting error is the last line
15:31:14 * abadger1999 here. Sorry I'm late
15:31:25 <felixfontein> #chair abadger1999
15:31:25 <zodbot> Current chairs: Xaroth abadger1999 acozine ariordan briantist felixfontein gundalow gwmngilfen-work samccann tadeboro
15:31:38 <acozine> I have not tested it myself, but my guess is that 3.x categorizes it as a warning, not an error?
15:31:56 <acozine> but 4.x calls it an error
15:31:58 <acozine> but that's a guess
15:32:03 <felixfontein> these warnings are not output by sphinx, but by antsibull before sphinx is run
15:32:08 <acozine> abadger1999: hi, welcome!
15:32:10 <felixfontein> or should be
15:32:16 <acozine> hmmmm
15:32:22 <felixfontein> line 9 is an actual error which (probably) breaks the build
15:32:39 <felixfontein> that message comes from sphinx, and is a problem with the antsibull sphinx extension
15:32:44 <felixfontein> which version of antsibull is that build using?
15:32:48 <gundalow> Yup, I was confused by it listed as a 4.x issue. Though I don't know the antusbull code that well
15:33:29 <felixfontein> the error with testing_formatter also looks strange, but shouldn't be related to the sphinx version either
15:33:57 <acozine> let me take a look
15:34:05 <samccann> so should we open an issue on antsibull with the error output and let y'all take a look?
15:35:14 <felixfontein> I would expect this to be the bug fixed in https://github.com/ansible-community/antsibull/pull/276, but that's already from May
15:36:09 <acozine> I got this information from Matt Clay, but I don't have all the details
15:36:18 <acozine> and i don't see a PR to work from
15:36:34 <acozine> so maybe he hasn't finished updating the requirements
15:37:03 <acozine> we should be using the latest version of antsibull, right?
15:37:36 <felixfontein> yes, or a new enough version
15:37:53 <acozine> okay, let me try again, and this time I'll test it locally also
15:38:43 <acozine> #action acozine to test Sphinx upgrade in CI for the devel branch
15:39:55 <acozine> and finally, here's the output of dericcrago's PR: http://docs.testing.ansible.com/ansible-core/devel/installation_guide/intro_installation.html#installing-ansible-on-debian
15:40:22 <acozine> I'm amused by `MATCHING_UBUNTU_CODENAME_HERE`
15:40:34 <acozine> overall, LGTM
15:40:55 <samccann> cyb-clock-clone wakes up to say we are 40 min into the meeting and into action item review
15:41:01 <acozine> heh
15:41:06 <acozine> oh, I'm way behind
15:41:23 <acozine> apparently we already merged the change to devel (the Debian install thing) and this is the backport to 2.11
15:41:31 <samccann> yep
15:41:37 <acozine> okay, I'll get that merged today
15:41:43 <samccann> that
15:41:48 <samccann> actually this is a 'test' issue
15:41:52 <samccann> PR that is.
15:42:03 <samccann> to see what it's like if I don't have merge rights for backports
15:42:19 <samccann> presumably it will be merged on the next release, if not sooner
15:42:26 <acozine> ahhh, so I shouldn't just merge it, I should let the process proceed
15:42:28 <acozine> phew
15:42:40 <samccann> yeah. I haven't pinged anyhone on core to merge it yet
15:42:58 <samccann> but perhaps we can quickly discuss - how critical is it that backports get merged between releases?
15:42:59 <abadger1999> Should samccann have merge rights?
15:43:10 <samccann> samccann is not sure she wants merge rights
15:43:22 <samccann> samccann could 'screw up a high mass' as her mum would say...
15:43:24 <acozine> this is for backports only
15:43:31 <acozine> she's got devel merge rights
15:43:45 <abadger1999> Otherwise i think we wouldn't have anyone on docs who can merge backports
15:43:48 <samccann> yeah so It's easy to ask for merge rights for backports. I'm just wondering how important it is to the community
15:43:57 <samccann> and yes, that's the state we are talking about.
15:44:49 <samccann> my worry is that frankly, with Alicia going, there is a ton of stuff I need to do/keep track of, etc.
15:45:04 <abadger1999> (possibly relevant... Now that a different team is releasing ansible-core, I'm not sure who is merging backports there anymore)
15:45:06 <samccann> So I thought - one less thing to track is minor releases and when the stable branch is frozen to merges.
15:45:28 <samccann> I had a handful that I noticed weren
15:45:42 <samccann> weren't merged, I asked core, and within an hour all were merged.
15:45:45 <felixfontein> maybe there could be a workflow that samccann approves docs backports, and that team merges them before releases (or also inbetween) if samccann approved them
15:46:03 <samccann> yeah that's what I was thinking felixfontein.
15:46:10 <abadger1999> I don't know if that team touches backports
15:46:19 <acozine> there are two docs backports open now: https://github.com/ansible/ansible/pulls?q=is%3Apr+is%3Aopen+label%3Adocs+label%3Abackport
15:46:32 <abadger1999> Has anyone checked if that's okay of what they do?
15:46:47 <samccann> I haven't asked core folks yet because I wanted to discuss
15:47:17 <acozine> in the past I've merged backports of urgent fixes, ones where we really wanted the `latest` docs updated right away
15:47:22 <samccann> if we feel I must have merge rights, I can ask for that. If we feel it's okay if backports linger for a week (or 3), then I can ask to implement what felixfontein said -
15:47:26 <acozine> and left lower-priority ones for the RMs to merge
15:47:57 <abadger1999> relrod: do you know if spredzy's team will be merging backports to ansible-core like you had been doing?
15:48:08 <felixfontein> samccann: usually they can linger, except if there are potential conflicts - but that's also a problem for regular backports
15:48:37 <abadger1999> Or is that responsibility going elsewhere?
15:50:26 <samccann> We have 10 min left to the meeting. I can followup on this later
15:50:44 <abadger1999> <nod>
15:50:55 <acozine> heh, it's one of those days
15:50:55 <samccann> #action samccann to discuss docs backport merging with core folks
15:51:15 <acozine> where we go over action items and then straight to the open floor
15:51:21 <acozine> #topic open floor
15:51:33 <acozine> all questions, comments, ideas, suggestions now welcome
15:51:50 <acozine> from anyone, you don't have to be a #chair (though you are welcome to become one!)
15:52:30 <acozine> we can talk about attributes if folks have ideas on that
15:53:36 <gwmngilfen-work> quick one
15:53:42 <gwmngilfen-work> (i've been in another mtg :P)
15:53:44 <acozine> go for it gwmngilfen-work
15:53:55 <gwmngilfen-work> matrix stuffs are going well
15:54:18 <gwmngilfen-work> is it worth backporting what we have so far in the communication doc (beacuse its one file)?
15:54:32 <gwmngilfen-work> or should it be all in one piece when we're done?
15:55:00 <acozine> we can backport it PR by PR
15:55:26 <abadger1999> Re: attributes, i was thinking maybe a list or table of the supported (full or partial) attributes on each plugin page (an empty list if no attributes are supported) with either a link to a page that describes all attributes or the definition of what that attribute means as part of the list.
15:56:12 <samccann> i feel like last time we talked attributes one or more people wanted the definition with the attribute so they don't have to go look it up?
15:56:34 <gwmngilfen-work> acozine: fair enough
15:56:36 <acozine> heh, that might be another use case for the expand/collapse feature
15:56:43 <gwmngilfen-work> i will keep going with my changes
15:56:51 <gwmngilfen-work> and we can decide when its ready to backport ;)
15:56:57 <gwmngilfen-work> i will link to devel for now ;)
15:56:59 <samccann> I'm reluctant to expand/collapse on the module pages
15:57:12 <acozine> fair enough
15:57:22 <samccann> they have a very useful toc on the top of each page that gets the reader to the spot they want. I feel like it would annoy people to have to expand from there
15:57:49 <acozine> gwmngilfen-work: i'm happy to open backports of the first two matrix docs PRs
15:58:00 <acozine> or to merge them if you open them
15:58:20 <acozine> samccann: yes, that's true
15:58:21 <felixfontein> abadger1999: I think also no support should be mentioned, since there's an important distinction between 'none' and 'not specified'/unknown
15:58:23 <abadger1999> One thing I'm not sure of is that attributes have several fields that may be interesting to users (description, type, i think I think one more). With a list, i suppose i'd be formatting that all into a single space.
15:58:41 <gwmngilfen-work> acozine: ok
15:59:18 <gwmngilfen-work> i can ask you/ samccann later for help with that :)
15:59:26 <abadger1999> felixfontein: i don't know about that... The way it's coded in core, i think plugins which have standard attributes will have a ton of unsupported attributes along with them
16:00:07 <samccann> so do we list all the attributes? That could get long
16:00:28 <samccann> so a table might be helpful (attribute | state| description)
16:00:30 <abadger1999> Or am i reading the code wrong?
16:01:22 <acozine> hm, we could simply not display any attributes that have `not specified/unknown` as the value
16:01:22 <felixfontein> abadger1999: by default a plugin will have no attributes, and if it has attributes, for these ones it has it has to specify the support (if it uses core's docs fragment, it will have a default 'support' value for all attributes in there)
16:02:08 <felixfontein> plugins that don't use the docs fragment can for example have the attribute `diff mode` with support `none`, but not have the attribute `check mode`. then we know the plugin doesn't support diff mode, but we don't know whether it supports check mode
16:02:20 <samccann> what does `support` mean in this context?
16:02:22 <felixfontein> which is different from not knowing whether diff mode is supported or not
16:02:36 <acozine> gwmngilfen-work: if you have the time and hte interest, you could test out our community instructions for backporting: https://docs.ansible.com/ansible/latest/community/development_process.html#backport-process
16:02:45 <abadger1999> felixfontein: right.  But if they do use the core docs fragment ( https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/doc_fragments/action_common_attributes.py ) then won't they get all of those attributes?
16:02:47 <felixfontein> ok diff and check only make sense for modules :)
16:02:48 * gwmngilfen-work copies that link
16:03:41 <felixfontein> samccann: it means that the plugin implements that
16:03:47 <samccann> cool thanks
16:04:23 <felixfontein> abadger1999: if they use the core docs fragment, they have to specify the support values which differ from the ones mentioned in there
16:04:34 <felixfontein> abadger1999: (which also implies that that docs fragment can never be extended with new attributes)
16:05:28 <samccann> is it possible that docs fragment is only useful to core (builtin) modules?
16:05:39 <samccann> and that we shouldn't suppose any collection wants to use it?
16:05:52 <felixfontein> that's a good question
16:06:03 <samccann> or if they do they should copy it into their own repo so  they can maintain it?
16:06:18 <acozine> it would be great to document whether collections-based modules support check mode
16:06:19 <felixfontein> it might actually be better, though I really don't like that either :)
16:06:44 <acozine> okay, I need to head to my next meeting
16:07:04 <felixfontein> probably it would be good if `support` has another possible value `unknown`, and that's the default
16:07:04 <acozine> I'm going to end the official meeting, but the chat can go on
16:07:07 <samccann> it just feels like a maintenance nightmare if a collection depends on this fragment but the fragment can be extended in the future
16:07:39 <acozine> make notes in https://hackmd.io/R71WLQjPQOa-Ze0Cg97V7A
16:07:56 <samccann> thanks acozine
16:07:59 <abadger1999> felixfontein: Yes.... but my thinking is that we don't want plugins which use the action_common_attributes doc_fragment show all 20+ attributes since they won;t implement most of them.
16:08:24 <acozine> thanks abadger1999 ariordan briantist felixfontein gundalow gwmngilfen-work samccann tadeboro!
16:08:31 <acozine> #endmeeting