15:01:19 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:19 <zodbot> Meeting started Tue Sep 14 15:01:19 2021 UTC.
15:01:19 <zodbot> This meeting is logged and archived in a public location.
15:01:19 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:19 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:19 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:26 <samccann> #topic opening chatter
15:01:30 <gwmngilfen-work> irc has no concept of room notifies, no. you could add "@room" to your keywords I guess :P
15:01:32 <gwmngilfen-work> oops
15:01:38 <samccann> So who's around to talk the docs?
15:01:54 <gwmngilfen-work> a bit. i have a 1:1 but I'm here :P
15:02:03 <samccann> i'm not in matrix yet, how many peeps are over there?
15:02:08 <ariordan[m]> I'm here.
15:02:28 <samccann> #chair ariordan[m] gwmngilfen-work
15:02:28 <zodbot> Current chairs: ariordan[m] gwmngilfen-work samccann
15:03:10 <samccann> andersson007_ dericcrago dmsimard gundalow  briantist cyberpear felixfontein mrproper[m] Xaroth you folks chatting docs today?
15:04:11 <felixfontein> o/o/
15:04:19 <tadeboro> o/
15:04:21 <samccann> ooo a dual wave!
15:04:34 <samccann> #chair tadeboro felixfontein
15:04:34 <zodbot> Current chairs: ariordan[m] felixfontein gwmngilfen-work samccann tadeboro
15:04:58 * dericcrago waves
15:05:06 <samccann> #chair dericcrago
15:05:06 <zodbot> Current chairs: ariordan[m] dericcrago felixfontein gwmngilfen-work samccann tadeboro
15:05:09 <gundalow> o/
15:05:12 <samccann> #topic Action Item review
15:05:16 <samccann> #chair gundalow
15:05:16 <zodbot> Current chairs: ariordan[m] dericcrago felixfontein gundalow gwmngilfen-work samccann tadeboro
15:05:41 <samccann> so I finally did my action items... woot for progress!
15:06:14 <samccann> I did create some mockups of how the attributes can be displayed (more on that later)
15:06:15 <samccann> and
15:06:35 <samccann> #info tracking issue for docs needs for ansible-core 2.12 release - https://github.com/ansible/ansible/issues/75664
15:06:47 <samccann> If you see anything missing from that list, please drop it in the comments.
15:06:57 <abadger1999> Ola
15:07:09 <samccann> Any other pending action items folks want to share status on?
15:07:13 <samccann> Welcome!
15:07:19 <samccann> #chair abadger1999
15:07:19 <zodbot> Current chairs: abadger1999 ariordan[m] dericcrago felixfontein gundalow gwmngilfen-work samccann tadeboro
15:08:53 <samccann> ok let's roll right into the Agenda then! https://github.com/ansible/community/issues/579#issuecomment-914485096
15:09:10 <samccann> #topic docs approach for new module attributes
15:09:54 <samccann> TL;DR; - some modules now support new plugin attributes feature. We have to decide what we want to display and how it will look
15:09:58 <samccann> #link https://github.com/ansible/ansible/issues/75164
15:11:11 <samccann> So I think I'm close to understanding this (emphasis on close)
15:12:15 <samccann> bcoca's last comment helped. If I'm interpreting it correctly, if a module includes the new common attributes docs fragment, that module is saying yes, all of these settings apply to this module. With the option to override a few of them.
15:12:26 <abadger1999> No
15:12:31 <samccann> heh
15:12:38 <samccann> that's what I get for thinking I understand it.
15:12:44 <abadger1999> Or at least, no more than any other module
15:13:00 <samccann> ok let's walk through this one scenario at a time.
15:13:02 <abadger1999> He is claiming that... But it's not true
15:13:31 <samccann> Module A - doesn't include the fragment, hasn't done anything for this new feature. What if any docs should be displayed?
15:14:13 <samccann> bcoca if you are around, please pipe in as there seems to be a disconnect here on how this is working/should work etc. And it's not something I can personally resolve in my head so it's holding up the docs effort here.
15:14:14 <abadger1999> I would say none: because it would just overload the user to list or all the things it does that are standard
15:14:39 <samccann> none makes sense to me as well. Is there anyone here who things Module A above should have any docs changes?
15:14:41 <samccann> #chair
15:14:41 <zodbot> Current chairs: abadger1999 ariordan[m] dericcrago felixfontein gundalow gwmngilfen-work samccann tadeboro
15:15:48 <tadeboro> I also think none is a sensible option here. If module authors did not do anything, why should new content show up in the docs.
15:16:00 <felixfontein> I don't think it should, since we have no idea which attributes the module implements or not
15:16:18 <felixfontein> it could support check mode (partially or fully), and it might not. it could support diff mode, but it might not
15:16:43 <samccann> #info if a module does nothing (doesn't include action_common_attributes) then no docs changes.
15:16:59 <ariordan[m]> cyb-clock-clone reminder - 15 minutes
15:17:03 <abadger1999> it most likely supports tags, loops, etc but it doesn't make sense to tell the user that since nearly all modules do.
15:17:34 <samccann> ok next one - Module B - includes the `action-common-attributes` but doesn't override anything. Can we assume it supports everything listed in that doc fragment?
15:17:43 <abadger1999> no
15:17:51 <abadger1999> However, terminology
15:17:54 <samccann> as in the module owner added it. So why add it if they don't support it all?
15:19:02 <abadger1999> We may be able to assume that the module does or does not support those things that are added as specified in the action-common-attributes file.    ie: some of the items in action-common-attributes are set to support: none, others to support: full.
15:19:06 <felixfontein> I think that if the module extends that docs fragment, but doesn't override anything, it basically says "I support exactly what the docs fragment says (as a default)"
15:20:05 <abadger1999> So in the file, there's { check_mode: { support: none }}    and { loops: { support: full }}
15:20:23 <samccann> ok my bad for using the wrong terminology
15:21:02 <tadeboro> But the problem I see here is: what happens if core adds other things to that fragment?
15:21:06 <samccann> Module B includes `action-common-attributes` docs fragment and does nothing else (no additions, no overrides). We display that table and all the info there applies.
15:21:40 <abadger1999> If Module B includes action-common-attributes and does not override anything, we can decide to document that it follows what it says and treat differences with actual behaviour as a bug that the module author should fix.
15:21:49 <samccann> #info if modules use this new docs attribute fragment, what happens if core adds more things to this common fragment?
15:21:50 <abadger1999> samccann: I would say no
15:21:58 <tadeboro> But this is not really a documentation problem, so I think "display the fragment unchanged" is OK.
15:22:46 <abadger1999> My reasoning for no would be the same as your Module A example: By putting in all the attributes which haven't changed from the defaults, you are overloading the end user with information.
15:23:07 <abadger1999> They can't see what's important anymore because there's too much non-important information.
15:23:51 <samccann> abadger1999 - so this brings up - what are the defaults? Because I'm pretty sure we already determined the docs fragment is not the defaults.
15:24:06 <samccann> and do they all HAVE defaults?
15:24:10 <abadger1999> samccann: right.  That's what needs to be added to the DOCUMENTATIOn schema.
15:24:34 <samccann> abadger1999 - so is there a defined list of defaults for each of these attributes?
15:24:36 <tadeboro> I see things a bit differently. If the module author does not include a fragment, there are no guaratees what module does so displaying info is a no-go. But if the author does include a fragment, it sends a signal that he/she/they wants to display that information to the users.
15:24:44 <felixfontein> tadeboro: I would argue that this fragment must never be extended :)
15:25:04 <abadger1999> From my comment o nthe issue: > (Note 2: Since ansible-core freeze is approaching, I just wanted to mention that implementing this needs changes to DOCUMENTATION as the current attributes code doesn't record what the default value is.)
15:25:51 <felixfontein> tadeboro: or only if the new properties must use some code in core that is added in the same PR which adds the property. but that's really hard to ensure.
15:26:09 <abadger1999> tadeboro: So.... If a fragment was small and targetted, I could see that.  Unfortunately, this fragment contains a bunch of unrelated stuff: https://user-images.githubusercontent.com/30267855/132581892-e27959da-085f-42df-996e-01933be09816.png
15:26:40 <abadger1999> I think it's unreasonable to expect a user to read that whole attribute table to pick out the one thing which is different than standard ansible.
15:27:36 <tadeboro> abadger1999: Ugh, there is a lot information in that table. Now I can see why we want to hide as much of this stuff as possible.
15:27:39 <samccann> abadger1999 - IF we had defaults, we could use color to denote what was overridden. But I am not hearing that there are defaults we can check against
15:28:02 <abadger1999> samccann: Yep.  We'd need to have a separate field that lists the default to know that.
15:28:10 <felixfontein> also for quite a few plugin types, quite a few of the entries make no sense
15:28:16 <samccann> alternately, we could display overrides in a unique color and leave everything else normal text
15:28:40 <samccann> #info quite a few plugin types, quite a few of the entries make no sense
15:29:11 <samccann> #info a table of all the attributes, especially where most are not overridden, can be information overload for the user https://user-images.githubusercontent.com/30267855/132581892-e27959da-085f-42df-996e-01933be09816.png
15:29:35 <felixfontein> (maybe there should be one docs fragment per plugin type?)
15:30:05 <ariordan[m]> cyb-clock-clone says we are 30 minutes into the meeting
15:30:20 <abadger1999> Another idea..... this specifc doc fragment could be changed so that everything has `support: unknown` and we make it policy that any other doc_fragment attributes must have support: unknown.  We don't display anything with support unknown and it is up to the plugin author to extend the doc fragment *and* override support in the attributes that they want to show up on their page.
15:30:30 <samccann> so this particular docs fragment - does it apply to just modules and not other plugin types? or is it already applying to multiple plugin types
15:30:55 <abadger1999> felixfontein: Maybe... I note that this one is named as if that's going to be the case (action_common_attributes... seems like it's for action plugins)
15:30:56 <felixfontein> abadger1999: I like this idea (and I think I suggested something similar in the past ;) )
15:31:19 <abadger1999> Although action and module's peculiar relationship means that some of the entries are for modules too.
15:31:20 <samccann> abadger1999  I like the idea but I feel like this is exactly what bcoca was against, based on comments. Maybe I'm misreading those
15:31:42 <abadger1999> yeah... he's against it... but he doesn't see the end result we want to have any value.
15:32:00 <abadger1999> he wants the full table to be displayed if a plugin extends that doc fragment.
15:32:44 <abadger1999> If we decide that the full table isn't helpful then a change has to be made.
15:32:47 <samccann> would it matter if we used the expand/collapse theme options here? like the table is collapsed by default and the reader clicks is, then sees the full table, with all overrides in purple or something?
15:33:07 <abadger1999> I don't think so because finding the relevant information is the same.
15:33:39 <abadger1999> Ah... changing the color of the overrides is fine.  But again, we'd need to know the default to know what overrrides are in place.
15:33:59 <samccann> the overrides are in the ..erm... module code, right?
15:34:10 <abadger1999> (note that making all supports: unknown in doc_fragments is a sneaky way of knowing the default... we know that the default is always unknwon)
15:35:00 <samccann> so what is this doing - https://github.com/ansible/ansible/pull/73707/files#diff-ac21bb72c5779d789c6981690c86de32cb1ae7ebce93b45d2abff7f15c979ad8R25
15:36:08 <samccann> I'd have thought we can detect where a module extends that doc fragment and any attributes listed would be in purple?
15:36:27 * samccann loves spouting nonsense about code magic she's clueless about in real life
15:38:44 <samccann> y'all went quiet. *knock knock* is this thing still on?
15:38:53 <gundalow> yup
15:38:54 <abadger1999> samccann: Hmmmm... Okay, so here's a different case.  I write collection foo.bar it has attribute does_foo  defined in foo.bar.doc_fragments.foobar.py .  It also copies a file using safe_file_operations from action-common-attriutes.   Since my foobar.py doc_fragment is targetted,I set supports: full on both of my attributes.  If we only display overrides in a different color, then the does_foo attribute will be hidden amongst
15:38:54 <abadger1999> all the action-common-attributes.
15:39:47 <felixfontein> it depends how you define overrides
15:39:56 <samccann> abadger1999 - again, sprinkling code magic - can't we tell that a new attribute is in a collection vs inheriting it from core?
15:40:22 <felixfontein> if you define it as "everything that has a different value than action_common_attributes or isn't in it"  then it's showing them as well
15:40:49 <samccann> OR are you suggesting the foo.bar collection adds an attribute, sqiggly, that is in their docs fragment as 'full' but then can be overridden within a module in that collection to be 'none' or something>
15:41:09 <samccann> aka - do we support 'overrides' within a single collection for their own attributes?
15:41:52 <abadger1999> samccann: But that's a false split.... I could have a collection foo.baz that has a doc_fragment similar to action-common-attributes with twenty entries and expect that anything that uses it is supposed to audit them all and override any that make sense.
15:41:54 <samccann> we could start with what felixfontein said - anything not matching the existing docs fragment gets purple text or soemthing
15:42:38 <abadger1999> So some collections could be providing doc_fragments like core and others like my other case example.... in code we have no way of knowing which way the collection is intended to work.
15:42:45 <samccann> ok so in the general sense - a docs fragment means 'add this stuff to my module docs'
15:43:05 <abadger1999> Correct.
15:43:17 <samccann> and it supports the ability to override it with local settings. But there's nothing today in a docs fragment that says 'only display part of this'
15:43:26 <abadger1999> Yeah.
15:43:50 <abadger1999> But because of the way the attributes are implemented, we need that ability.
15:44:38 <samccann> would I be totally out of line and a docs curmudgeon if I said docs can fix what may be an implementation issue?
15:44:58 <ariordan[m]> cyb-clock-clone says we are 45 minutes into the meeting
15:45:11 <samccann> thanks ariordan[m]!
15:45:24 <samccann> So what are our tangible next steps on this one?
15:45:58 <abadger1999> (attributes could also be implemented in docs_fragments so that only a related group of attributes are together [I may want to specify safe_file_operations separate from loops therefore they need to be in separate files.... but felixfontein pointed out that that will cause problems down the road because that means collections have to require a specific version of core.)
15:46:24 <samccann> I see two options - we display the docs fragment and sprinkle some color to denote overrides or any attribute that's not in the common fragment.
15:46:36 <samccann> or someone goes back to core and gets a different implementation
15:46:38 <abadger1999> samccann: From what youve said in the past, dylan has given docs the impramatur to make these types of decisions.
15:47:19 <abadger1999> (I also note that the proposal for attributes is wholly about making documentation better.... so if the current work makes documentation worse, then we should be able to say that it needs to be changed)
15:47:34 <samccann> abadger1999 agreed but 1 - we don't have alicia who has the technical knowlege to help here, 2 - we have two weeks or less to get any core change discussed, approved, and coded.
15:48:21 <abadger1999> I think the easiest thing would be to make all the doc_fragments specify support: unknown and plugins must override supports for any attribute that they support.
15:48:55 <tadeboro> And then we only show the overriden ones, right?
15:48:56 <abadger1999> That wuold be a change to data, not to code.
15:49:01 <abadger1999> Yep.
15:49:04 <samccann> ok so that would be option 3 - change it to support:unknown etc.  If that happens, does that make all this workable?
15:49:11 <abadger1999> felixfontein: ^ That will cover everything you can think of,  right?
15:49:55 <abadger1999> Yes.... It would look like this:
15:50:00 <felixfontein> I think it does
15:50:23 <tadeboro> I think this is the best option I heard thus far. Module authors get unified descriptions that do not have to be copy-pasted around, and they retain the ability to specify exactly what info they want to expose to the users.
15:50:39 <abadger1999> all docs fragments (specifically in what we're talking about, action_common_attributes) have all entries specify support: unknown.
15:51:07 <felixfontein> there could be a sub-fragment inside the main fragment which contains the existing defaults, so that in core most things don't have to change
15:51:23 <felixfontein> (that fragment won't be around in older ansible versions though)
15:51:28 <abadger1999> Any thing which extends a doc_fragment to get attributes will extend the fragment and also add overrides to support: [full|none|partial]
15:51:39 <felixfontein> (subfragment = something not called DOCUMENTATION, but say ANSIBLE_CORE_DEFAULTS)
15:51:53 <samccann> ok between the two of you (abadger1999 and felixfontein) can you write up this proposal and I can bring it to the Docs Powers That Be and core for discussion?
15:52:07 <abadger1999> our documentation generation will not display the attribute if it has suppports: unknown
15:52:19 <felixfontein> I think I can implement that pretty quickly
15:53:17 <samccann> #info general consensus is to use support:uknown in the action_common_attributes and then any module using it must override for what it actually supports. Docs will display those overrides only.
15:53:22 <abadger1999> felixfontein: what would the subfragment get us?  (an example of something you think would have to change without it)
15:53:34 <tadeboro> I can comment on the results, but cannot help with the code much (my coding foo is deteriorating rapidly since my role at $job changed ;))
15:53:41 <abadger1999> :-)
15:54:32 <tadeboro> I need to run. Feel free to cc me on the proposal/implementation/whatever. Nice talking to you all!
15:54:39 <samccann> thanks tadeboro!!
15:54:41 <tadeboro> #unchair tadeboro
15:54:41 <zodbot> Current chairs: abadger1999 ariordan[m] dericcrago felixfontein gundalow gwmngilfen-work samccann
15:54:44 <abadger1999> tadeboro: Tchau tadeboro!
15:54:45 <felixfontein> abadger1999: mainly that the change to ansible-core would be minimal
15:55:25 <samccann> ok if the two of you can create some kind of writeup on this, I can take it to others and see how far we get with that docs mandate ;-)
15:56:04 <samccann> meanwhile, gonna open the floor
15:56:08 <samccann> #topic Open Floor
15:56:14 <abadger1999> felixfontein: Okay... but what are you thinking would change if we didn't have it?  I don't see anything that would change.
15:56:24 <samccann> Here's your chance to ask our fav docs question? pull up a PR etc?
15:56:50 <ariordan[m]> I have a PR: https://github.com/ansible/ansible/pull/75703
15:57:31 <felixfontein> abadger1999: you'd have to modify all modules which extend that fragment and paste all missing attributes in there with the current defaults
15:57:35 <abadger1999> felixfontein: Oh... do you mean, you think that the copy module, for instance, should display all of the attributes from action_common_attributes even though it only overrides three?
15:57:36 <samccann> folks - can we get some technical eyes on ^^?  it needs a technical person to approve before we can merge
15:57:40 <samccann> #chair
15:57:40 <zodbot> Current chairs: abadger1999 ariordan[m] dericcrago felixfontein gundalow gwmngilfen-work samccann
15:58:03 <abadger1999> felixfontein: If so... I suppose we need a vote on that because I don't think we would want that.
15:58:28 <felixfontein> abadger1999: no, I mean if we change the default support state to 'unknown', we'll have to modify every module in core to list support state for ALL attributes
15:58:33 <felixfontein> except if we use a fragment for that
16:00:04 <ariordan[m]> cyb-clock-clone says we are 60 minutes into the meeting
16:00:07 <abadger1999> felixfontein: What would the practical effect of changing those states from unknown be, though?
16:00:18 <abadger1999> We still wouldn't want them to be displayed i nthe documentation, right?
16:01:00 <felixfontein> abadger1999: unknown would be wrong, since their support state **is** known
16:01:11 <felixfontein> but yes, this doesn't help for displaying the values
16:01:17 <samccann> so what docs displays must be useful and not add to confusion. So anything in an attributes table MUST be a known state. full support, no support, etc
16:01:18 <abadger1999> <nod>
16:01:39 <abadger1999> Could we use different terminology?  "unspecified" ?
16:01:42 <felixfontein> (for that we probably have to hard-code this list in antsibull)
16:02:01 <samccann> what is the purpose to display an unspecified state?
16:04:22 <felixfontein> https://github.com/ansible/ansible/pull/75705
16:04:25 <abadger1999> samccann: We wouldn't display it... I think that felix is objecting to saying that the core modules which have already started using extends_fragment: action_common_attributes have state unknown since we do know what the state is.  We still don't want to display them but saying "unknown" is untrue.   I'm wondering if changing the name of this value to "unspecified" is enough so that he feels comfortable.
16:04:56 <felixfontein> unspecified would be very unhelpful for users looking at the ansible-doc output
16:05:12 <felixfontein> because they have no clue whether this attribute is supported or not
16:05:21 <felixfontein> (if they don't know the default value by heart)
16:05:55 <abadger1999> felixfontein: oh... but won't doing it that way mean that a module like copy will get all the attributes displayed again?
16:06:02 <felixfontein> 'unspecified' would only work if there's a separate field containing the default value
16:06:35 <abadger1999> (the way you have in your PR)
16:06:50 <samccann> ok so we have `action_common_attributes` and we set support:uknown for all of them.
16:07:03 <felixfontein> abadger1999: depends on how the program processing the output is implemented. antsibull could contain a list of default values, and only show attributes which differ from the default values
16:07:13 <samccann> Then each module overrides whatever they DO have a state for (full support, no support, etc)
16:07:29 <samccann> and we display those overrides.
16:07:53 <abadger1999> felixfontein: antsibull cannot have a list of default values unless we add a default to the DOCUMENTATION metadata.
16:08:00 <felixfontein> abadger1999: do we only want to solve the problem on the docsite, or also on CLI output?
16:08:05 <samccann> I feel like attributes do NOT have default values, period.
16:08:10 <abadger1999> felixfontein: because a collection could implement something similar to action_common_attributes.
16:08:17 <felixfontein> abadger1999: well, we can hardcode one :) (but yeah I'd like to avoid that too)
16:08:51 <felixfontein> abadger1999: if we show a subset of the attributes for a collection, we must provide a way to show *all* of them as well
16:08:52 <abadger1999> felixfontein: and a hardcoded list in antsibull wouldn't know about the collection's thing.
16:09:32 <abadger1999> felixfontein: we'd also, then, need core to update antsibull's list whenever they added a new attribute.
16:09:40 <felixfontein> for standard attributes we can simply create one page with them and link to it. but we can't do that for collection attributes.
16:10:01 <felixfontein> abadger1999: yes, or else it will show up for all (core) modules
16:10:10 <abadger1999> felixfontein: I had been planning to do that, at least at first.  (a single page with all attributes.  Like a glossary)
16:10:37 <felixfontein> but that doesn't work with collection attributes IMO, since even one collection could use the same attribute name with different descriptions
16:11:11 <felixfontein> the only attributes we can be *a little bit* sure about are the "standard ones" from ansible-core
16:11:13 <abadger1999> felixfontein: Maybe we need to also mandate that collection attributes use a fqcn form?
16:11:36 <abadger1999> I thought of that a coupe meetings ago but forgot it as we talked about other things :-/
16:12:09 <felixfontein> it might be a good idea
16:12:52 <samccann> just realized the meeting is still running. Do y'all want me to end it, or do you want this to continue so we have it all in the log to refer back to?
16:12:58 <abadger1999> felixfontein: Re: CLI, I think we should also fix it in the CLI but dylan will probably need to weigh in as to whether docs has that mandate or not.
16:13:20 <abadger1999> I think felix and I are both chaired so let's let meetbot run.
16:13:24 <felixfontein> one big problem with attributes is that the proposal that's implemented is not really compatible with what docs WG wants
16:13:34 <abadger1999> You can tell everyone else that the meeting is officially ended, though.
16:14:44 <samccann> heh yeah anyone still hanging around - this meeting will just continue the above discussion.  Listen in/munch popcorn if you like or wander off... but thanks for attending!
16:16:03 <abadger1999> felixfontein: yeah.   I think the solution to that is probably that the DOCUMENTATION, RETURN, etc schemas shouldn't be modified until docs gets a chance to implement the code to pull it into the docs.
16:16:12 <felixfontein> I will have to leave pretty soon though :/
16:17:00 <abadger1999> felixfontein: Okay... so.. let me type where I think we/I am at and you can tell me if you think that's okay too.
16:17:00 <felixfontein> abadger1999: that will help in the future, but not for attributes :)
16:17:09 <samccann> so we're back to next steps - what can we hope to happen in 2 weeks that's left, knowing core feels this feature is complete for now
16:17:11 <felixfontein> abadger1999: sounds good!
16:17:41 <felixfontein> thanks everyone!
16:17:56 <felixfontein> I'm off now :)
16:19:17 <samccann> abadger1999 - are you writing up the option to have the existing fragment say unknown and for now we go in and add all the other overrides to the existing modules that support this? It's a growing list
16:20:21 <samccann> meanwhile
16:20:25 <samccann> #endmeeting