14:31:05 <acozine> #startmeeting Documentation Working Group aka DaWGs
14:31:05 <zodbot> Meeting started Tue Oct 27 14:31:05 2020 UTC.
14:31:05 <zodbot> This meeting is logged and archived in a public location.
14:31:05 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:05 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:05 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
14:31:07 <felixfontein> acozine: what time is it for you right now?
14:31:12 <acozine> #topic opening chatter
14:31:22 <felixfontein> (I got up at 5:20 today, you probably can't beat that :P )
14:31:22 <acozine> felixfontein: it's 9:30 in the morning
14:31:30 <acozine> oof
14:31:37 <acozine> I am not a morning person at all
14:32:00 <acozine> my previous job had daily standup at 9:30, and I worked there for 7 years, so it got to be a habit
14:32:08 <acozine> "sit down at desk at 9:30"
14:32:29 <acozine> I do try to make it a bit earlier
14:32:31 <felixfontein> the nice part of getting up very early is that you can work a couple of hours, and then it's still early ;)
14:32:45 <acozine> yeah, that does sound nice
14:32:54 <acozine> but if I get up too early, my brain just doesn't work well
14:33:22 <acozine> so I can be at my desk but I'm not sure it really counts as "working"
14:33:34 <felixfontein> showering usually helps. without I need quite some time to be functional...
14:33:47 <acozine> yeah, and caffeine helps
14:33:54 <bcoca> felixfontein: copious ammounts of coffee ...
14:34:03 <acozine> anyway, next week it will be 8:30, which isn't really that early
14:34:22 <acozine> even I can manage it, and function well, as long as I remember ;-)
14:34:30 <felixfontein> hehe :)
14:34:56 <acozine> #chair bcoca felixfontein lmodemal
14:34:56 <zodbot> Current chairs: acozine bcoca felixfontein lmodemal
14:35:01 <acozine> who else is around?
14:36:07 <acozine> gundalow: alongchamps andersson007_ baptistemm briantist cyberpear madonius tadeboro tremble you folks talking docs today?
14:36:41 * tremble lurks
14:36:43 <acozine> I ping people who have participated before . . . but newcomers are always welcome
14:37:40 <acozine> so if you're thinking, "she didn't ping me, I'm not really part of the group" . . . please know that we'd love to have you join in!
14:37:46 <acozine> #chair tremble
14:37:46 <zodbot> Current chairs: acozine bcoca felixfontein lmodemal tremble
14:38:04 <acozine> tremble: if you're feeling low-profile enough that you don't want to be furniture, let me know
14:38:28 * tremble shrugs :)
14:38:49 <acozine> heh
14:39:20 <acozine> #topic index pages for modules/module plugins
14:39:25 <acozine> https://github.com/ansible-community/antsibull/pull/196
14:40:11 * baptistemm will lurk also from far far away
14:40:19 <acozine> felixfontein brought up the question, should the auto-generated module docs say `modules` or `module plugins`?
14:40:23 <felixfontein> #chair baptistemm
14:40:23 <zodbot> Current chairs: acozine baptistemm bcoca felixfontein lmodemal tremble
14:40:40 <acozine> heh, we have rows of chairs today
14:40:42 <felixfontein> well, actually T. brought up the question, I just forwarded it here :)
14:40:52 <acozine> ah, thanks
14:40:59 <baptistemm> ah the meeting is one hour sooner now for me
14:41:13 <felixfontein> I was assuming that 'modules' sounds better than the current 'module plugins'
14:41:24 <felixfontein> baptistemm: same here :)
14:41:32 <acozine> it does sound better, but I think one of the goals of collections was to "elevate" non-module plugins
14:42:00 * alongchamps lurking and on another meeting
14:42:15 <acozine> heh, back row, then, alongchamps?
14:42:22 <alongchamps> yup :)
14:42:28 <acozine> #chair alongchamps
14:42:28 <zodbot> Current chairs: acozine alongchamps baptistemm bcoca felixfontein lmodemal tremble
14:42:28 <bcoca> well, also 'module plugins' sometimes are just 'action plugins' ... like 'template'
14:42:50 <bcoca> actions and modules are very closely intertwined
14:42:51 <felixfontein> bcoca: true, but action plugins are listed alongside modules and are indistinguishable to the user :)
14:42:54 <acozine> bcoca: how important is it that users understand that?
14:43:19 <bcoca> acozine:  depends .. most of the time, not at all, but when they need the distinction it matters a lot
14:43:31 <bcoca> for example 'which server does src: refer to'
14:44:30 <acozine> is that something we should note in the docs for the individual plugin? or is it better to educate all users about that concept?
14:45:05 <felixfontein> I think most action plugins already mention explicitly where they get the files from
14:45:07 <bcoca> docs building should already show 'this module has a corresponding action plugin' but my guess is most people dont see that
14:45:27 <bcoca> felixfontein: yes, they should ... but also requires being read ...
14:45:29 <felixfontein> bcoca: docs building doesn't know, since ansible-doc -l doesn't tell :)
14:45:50 <bcoca> felixfontein: it did before, so unless it was taken out ...
14:47:30 <bcoca> seems it was removed, but at one point it did have that notice
14:48:00 <felixfontein> acozine: good question
14:48:09 <acozine> felixfontein: will the final mega-index page be alphabetized? so it will list `action plugins` then `connection plugins` and so on, with `modules`/`module plugins` further down the page?
14:48:40 <bcoca> acozine: action plugins are currently not listed since they are 'blended' with modules
14:48:50 <felixfontein> acozine: there's one page per category (which is grouped by collection, and I think both collections and plugins in it are sorted alphabetically)
14:48:51 <bcoca> docs for action plugin would be in module, see 'template'
14:49:10 <acozine> is there a top-level index page?
14:49:22 <acozine> a kind of "list of all plugins by plugin type"?
14:49:38 <bcoca> `lib/ansible/cli/doc.py:            text.append("  * note: %s\n" % "This module has a corresponding action plugin.")` <= felixfontein ansible-doc still returns this info .. for some reason its not  in the html anymore
14:49:39 <felixfontein> acozine: right now no. resp., that would have to be done manually right now. do you think an auto-generated one is needed?
14:50:23 <felixfontein> bcoca: I can't see that information in the --json output
14:50:32 <acozine> no, but if there is one, or will be on, then having `module plugins` there, at least, seems more harmonious than `modules`
14:50:59 <felixfontein> acozine: the difference `module plugins` / `modules` is already visible on the per-collection plugin index page
14:51:20 <bcoca> felixfontein: hmm, its now only part of formatting, which json option bypasses, but easy enough to generalize
14:51:47 <felixfontein> acozine: compare https://ansible.fontein.de/collections/community/sops/index.html#plugins-in-community-sops and https://docs.ansible.com/ansible/latest/collections/community/kubernetes/
14:52:17 * gundalow waves
14:52:27 <gundalow> (clocked changed and I got confused)
14:52:29 <felixfontein> #chair gundalow
14:52:29 <zodbot> Current chairs: acozine alongchamps baptistemm bcoca felixfontein gundalow lmodemal tremble
14:52:31 <lmodemal> Hi gundalow!
14:52:59 <acozine> welcome gundalow - we're debating `modules` vs `module plugins`
14:53:29 <acozine> felixfontein: yeah, whatever we do on the index pages, we should do on the collections pages
14:53:52 <felixfontein> brb in 4 minutes
14:54:15 <acozine> I lean toward `modules` because that's the term everyone has used for years
14:54:42 <gundalow> likewise
14:55:01 <tremble> Personally I find it confusing if 'official' docs aren't consistent in how they name things.  If they're technically "Module plugins" then it's better to use that name consistently, or drop it.
14:55:11 <gundalow> I know technically modules are a subset of plugins, though I've always viewed that as an implementation detail
14:55:32 <acozine> tremble: agreed, we should be consistent
14:55:38 <gundalow> #action Update styleguide with whatever naming convention is decided
14:55:53 <acozine> thanks gundalow
14:56:03 <alongchamps> +1 on consistency
14:56:11 <gundalow> +1 to `modules` from me
14:56:31 <acozine> shall we have a poll?
14:57:01 <bcoca> depends on what you are reffering to, since they are actually 'action' in the synatax
14:57:07 <bcoca> action/local_action for a task
14:57:19 <felixfontein> re
14:57:49 <lmodemal> I dont' know if my vote counts since I'm new here, but I like modules :)
14:58:07 <acozine> bcoca: from a coding perspective, that is true, but from a findability perspective, people search for `X module` not for `X module plugin` or `X plugin`
14:58:21 <acozine> lmodemal: every vote counts
14:58:30 <lmodemal> Thanks acozine!
14:58:44 <felixfontein> bcoca: do you know whether core team has a preference?
14:58:53 <bcoca> acozine: in the docs we to make those equivalents, specifically when we introduce actions we say 'they are normally performed by a module'
14:59:03 <bcoca> felixfontein:  13 or 17 of em
14:59:51 <bcoca> this might become a more/less important distinction in future once we get to 'controller side argspec'
15:00:12 <acozine> what will Controller Side Argspec change/do?
15:00:20 * felixfontein is also wondering that
15:00:44 <bcoca> opens up many posibilities , depending on feature it will either increase the need of the distinction or make it irrelevant
15:01:20 <bcoca> example: module specifies 'controller_src_handler' so it automatically uses 'action plugin' to handle that .. would be less of a need for a 'copy action plugin' + 'copy module'
15:02:40 <felixfontein> i.e. the action plugin handles argspec validation, resp. something before the action plugin?
15:02:56 <felixfontein> and the module just gets the evaluated result with defaults filled in and conversions made?
15:04:53 <acozine> consensus from those I've been able to reach is "we should just call them `modules`"
15:05:03 <bcoca> felixfontein: no mostly would work like modules, action plugin would use
15:05:33 <acozine> the only objection I have is that we have to special-case them in the collections docs build
15:05:50 <acozine> but I think that's worth it for predictability, findability, and consistency
15:06:32 <felixfontein> acozine: IMO the special casing needed is not that much (in fact two places including the plugin indexes)
15:06:56 <acozine> if we need notes in the modules that use action plugins, we can solve that in the individual module docs
15:07:00 <acozine> felixfontein: excellent
15:08:04 <felixfontein> it's probably a good idea to have that information that a module has an action plugin in the module docs. that needs an ansible-doc change though. but that should be easy.
15:08:14 <felixfontein> (as ansible-doc already knows)
15:08:34 <bcoca> felixfontein: just need to move the handling from just manpagish output to general
15:08:51 <felixfontein> bcoca: I can create a PR for that
15:08:55 <felixfontein> (or at least try :) )
15:09:21 <bcoca> not hard, you really only need t6o move the detection, then you get action: true/false in json to indicate it exists
15:09:27 <bcoca> rename to has_action?
15:09:50 <felixfontein> sounds good
15:11:02 <acozine> #agreed we prefer `modules`  to `module plugins` in the documentation, we should use `modules` consistently
15:11:45 <acozine> #action update index page PR and docs build to use `modules` everywhere
15:12:38 <gundalow> \o/
15:14:00 <lmodemal> \o/
15:14:00 <acozine> #topic splitting ansible-base from ansible package docs
15:15:39 <felixfontein> the heavy stuff.
15:17:04 <acozine> heh
15:17:22 <lmodemal> uh oh..
15:17:30 <acozine> this topic is partly a reminder and partly a brainstorming session
15:18:06 <acozine> how can we present documentation so that users understand the difference between ansible-base and the ansible package?
15:18:44 <acozine> especially if the most recent version of ansible-base is not included in the most recent version of the ansible package?
15:20:05 <gundalow> 1) Do (should) they care?
15:20:06 <gundalow> 2) Does this come back to personas again?
15:21:18 <gundalow> 3) Are there any other projects that ship n-1 that we can look at?
15:21:25 <acozine> 1) only if the latest ansible-base has features that are not in the latest ansible package - if that's the case, we need to document those somewhere in a way that helps users understand whether or not they have those extra features available
15:21:28 <acozine> 2) yes
15:21:41 <acozine> 3) hm, I do not know . . .
15:22:01 <felixfontein> 1) the latest ansible-base "always" has some new features, or some things removed.
15:22:23 <tremble> 1) They're going to care when it comes to features and deprecations.
15:23:17 <felixfontein> 2.11, 2.12, 2.13 and 2.14 will all have breaking changes, judging from grepping for removal versions
15:23:48 <acozine> we have a bunch of options that would build on the current organization of docs
15:24:22 <acozine> but implementing them may get complicated
15:24:28 <acozine> for example, we could generate a docsite for `docs.ansible.com/ansible-base`
15:24:38 <acozine> and that could have its own versioning
15:25:51 <acozine> we would have to build another pipeline (maybe not so complicated)
15:25:56 <felixfontein> is there any other (viable) solution than having two different docsites?
15:26:31 <felixfontein> (except having a docsite per collections + ansible-base combinations, which is a lot more and probably even more complicated)
15:27:04 <gundalow> Stepping back at bit. We have various indepently installable things (ansible-base, collections*, `ansible`, lint, molecule, etc). Each of them can be released independently, some of them may be meta packaged together
15:28:10 <felixfontein> ansible-base (with version V1) and collections (with versions V2,...,Vn) = ansible (combined version V1,V2,...,Vn)?
15:28:24 <acozine> documentation pick-n-mix?
15:28:58 <gundalow> acozine: yup, that's what I'm wondering
15:30:18 <acozine> so how would that work? a home page for docs with five dropdowns where you pick your versions? most users don't ever hit the home page, they go straight from google to a page in `latest` . . . what happens to those users?
15:31:02 <felixfontein> there are too many collections to make this viable
15:31:12 <felixfontein> (at least with the current 'static site' approach)
15:31:57 <gundalow> might not be applicable for collections
15:32:03 <gundalow> Trying to find examples: https://docs.microsoft.com/en-us/visualstudio/?view=vs-2019
15:32:14 <felixfontein> also ansible version is alraedy a combination of ansible-base version and collection versions, so being able to chose by that is good - except for people who want to select by ansible-base version
15:33:05 <gundalow> RHEL: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/
15:34:56 <gundalow> I don't have a picture in my mind :(
15:35:05 <acozine> in that style, version is the primary choice . . . meaning once you choose a version, you no longer have the option to "see this content in `version-1`"
15:35:38 <acozine> this isn't something we can solve today
15:35:51 <acozine> but the complexity of it means we should revisit the question every week
15:36:00 <acozine> because we will need a solution
15:36:10 <acozine> possibly soon
15:36:16 <acozine> s/possibly/probably/g
15:36:40 <felixfontein> bcoca: https://github.com/ansible/ansible/pull/72359
15:38:14 <acozine> but we are over time (again)
15:38:27 <acozine> and I'd like to touch on a few more things, if folks can hang around for a bit
15:38:45 <felixfontein> I'm still here
15:38:55 <acozine> #topic config page updates, PR https://github.com/ansible/ansible/pull/72354
15:38:55 <lmodemal> I'm here
15:39:04 <acozine> yay!
15:39:39 <felixfontein> also thanks to bcoca, who already did most of the work a long time ago!
15:40:26 <acozine> this looks fantastic to me - compare the current page: https://docs.ansible.com/ansible/latest/reference_appendices/config.html#ansible-configuration-settings to the proposed page: https://gist.github.com/felixfontein/d6281c46f561107ae43f23c5f21f497f
15:40:40 <bcoca> http://paste.debian.net/1168831/ < felixfontein
15:41:19 <bcoca> ah .. thought i had merged that .. so config page was still not showing 'lists' correctly?>
15:41:59 <bcoca> felixfontein: lol ... same code you already wrote ...
15:42:07 <bcoca> +100
15:42:16 <acozine> bcoca: felixfontein great minds really do think alike!
15:42:30 <felixfontein> bcoca: almost :) I think you insert has_action one level higher, but don't access it from there
15:42:35 <bcoca> slightly diff location
15:42:44 <bcoca> yep
15:42:50 <bcoca> shoudl be 'doc'][
15:42:58 <felixfontein> well the solution is not that hard to come up with :)
15:43:05 <bcoca> i was writing mine in middle of 2 other meetings ...
15:43:11 <bcoca> yep, yours lgtm
15:43:39 <bcoca> but move the '#generate extra data' comment  also
15:43:45 <felixfontein> acozine: I don't know the new page renders with sphinx
15:43:49 <bcoca> or copy ...
15:44:02 <acozine> felixfontein: ah, okay, I can publish it to the test site
15:44:33 <acozine> #action acozine to publish PR 72354 to testing.docs.ansible.com
15:44:52 <felixfontein> acozine: I think that would help, to be on the safe side :)
15:45:06 <bcoca> felixfontein: also something we might want to backport even up to 2.9
15:45:07 <acozine> yep, belt and suspenders
15:45:39 <acozine> bcoca: you mean the config docs PR or the has_action PR or both?
15:46:05 <bcoca> both
15:46:14 <acozine> sounds good
15:46:15 <felixfontein> bcoca: do you mean the config formatting, or has_action?
15:46:16 <bcoca> also need to get 'plugin configs' there
15:46:39 <bcoca> since they mostly affect doc formating and the old pages are 'slightly incorrect' i think its worth backporting
15:47:33 <acozine> okay, last topic before the open floor . . .
15:47:42 <acozine> #topic sphinx plugin work
15:48:17 <acozine> https://github.com/felixfontein/ansible-basic-sphinx-ext
15:48:25 <felixfontein> bcoca: comment added to #72359
15:48:49 <felixfontein> acozine: last week at some meeting (not sure anymore) there was the idea of integrating it with antsibull
15:49:08 <felixfontein> I guess that's something that should be discussed with T.
15:49:10 <acozine> felixfontein: that sounds like a good idea, what was the consensus at that meeting?
15:49:30 <felixfontein> acozine: I think it was "let's see what T. says next week" :)
15:49:31 <acozine> yeah, is T back this week? or not until next week?
15:49:38 <felixfontein> yep, he was around yesterday
15:49:42 <acozine> awesome
15:49:43 <felixfontein> though all-day meetings then
15:49:51 <acozine> ah, yeah
15:50:33 <acozine> okay, I'll put the sphinx plugin back on our agenda for next week
15:50:40 <acozine> thanks!
15:50:47 <acozine> #topic open floor
15:51:25 <acozine> what did we miss today? does anyone have a comment, question, suggestion?
15:51:30 <acozine> or a PR we should be looking at?
15:51:41 <acozine> or an issue we should be looking at?
15:51:51 <felixfontein> https://github.com/ansible/ansible/pull/72335 maybe ;)
15:52:07 <bcoca> https://github.com/ansible/ansible/pull/67435 create docs at all
15:53:19 <bcoca> https://github.com/ansible/proposals/issues/68 <= also would like to standarize this before 'controller side argspec' happens
15:54:21 <felixfontein> what's the timeline for controller side argspec?
15:54:59 <bcoca> we were supposed to add it in 2.4
15:55:17 <bcoca> now, if i can get all ducks in row, i want to push for 2.11
15:55:32 <felixfontein> so when extrapolating, 2.123?
15:56:12 <acozine> bcoca: yes, we can create some documentation to go with the code that allows running playbooks from collections (67435)
15:56:50 <bcoca> acozine: not somethign we need right now, also coord with dylan on what usages we want to stress, just adding it there to reserve mind space
15:57:09 <acozine> felixfontein: thanks for the link to 72335 - it looks like good information, I need to generate it to see how it looks before merging
15:57:48 <felixfontein> bcoca: about the proposal, I guess we need to nail down some specifics first - like where can the things be defined, can collections define their own, can collection overwrite ansible-base, need to use FQCN to avoid collecitions, ...
15:58:43 <felixfontein> acozine: I assumed the summer intern was no longer working on this
15:58:49 <bcoca> felixfontein: for the properties? they are specific to the plugin, not matter where they reside, the convention is about behaviours with core, not sure if we want to add special behaviours for specific collecitn plugins
15:59:28 <felixfontein> bcoca: I mean where to define meanings of the properties
15:59:46 <felixfontein> bcoca: resp. who can, what's precedence or whether properties need FQCN to avoid collisions, ...
16:00:48 <bcoca> ah, yeah, if you are creating custom ones, but in general these are just refering to behaviours related to core execution, so not really seeing the need for that
16:01:35 <bcoca> do you have a use case?
16:01:38 <felixfontein> bcoca: people would want to use this for their own properties as well :) some properties that only make sense for amazon/aws modules for example
16:02:17 <bcoca> like 'no aws tag support' ?
16:02:35 <bcoca> hmm, might need to find a good map to doc fragments then
16:02:40 <felixfontein> yes, or it could be used as a 'tag', like to which part of AWS it applies
16:02:48 <felixfontein> (if that isn't clear from the module/plugin name)
16:03:13 <felixfontein> if that feature is there, people will find a lot of good (and some not so good) uses for it
16:04:18 * acozine a bit distracted for a second
16:04:34 * bcoca is meeting bouncing
16:05:28 <felixfontein> btw, bcoca, can you take another look at https://github.com/ansible/ansible/pull/71824 ?
16:05:53 <bcoca> was trying to before allthemeetings
16:07:23 <acozine> felixfontein: the summer intern is gone, true
16:07:55 <acozine> thank you for picking up that thread
16:08:15 <acozine> thanks for the open floor entries bcoca felixfontein
16:08:35 <acozine> I hope we can merge at least a few before next week
16:08:49 <acozine> we've now gone 40 minutes over, though
16:08:50 <felixfontein> sounds great!
16:08:57 <felixfontein> time to go back to work ;)
16:09:12 <acozine> thanks everyone! (including lurkers!!!)
16:09:17 <acozine> #endmeeting