16:02:10 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:02:10 <zodbot> Meeting started Tue Nov 29 16:02:10 2022 UTC.
16:02:10 <zodbot> This meeting is logged and archived in a public location.
16:02:10 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:02:10 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:02:10 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:02:11 <samccann> And welcome Zurich!
16:02:23 <felixfontein> o/
16:02:29 <samccann> and I was blaming myself for that one Gwmngilfen
16:02:43 <oranod> James Joyce's grave is in Zurich. just a bit of interesting info for your day.
16:02:43 <samccann> oh that is interesting. TIL
16:02:55 <oranod> it's actually a nice place to visit
16:02:55 <samccann> @room Meeting time! Who is here to talk the docs?
16:02:56 <oranod> o/
16:02:56 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
16:03:12 <felixfontein> oranod: hmm, interesting, never heard about that before :)
16:03:13 <samccann> To any newcomers - again, welcome. We chair all attendees as a way of recognizing your time spent here. And it opens it up for people to add to the meeting minutes with commands like #info or #link (to add a link)
16:03:13 <samccann> #chair Don Naro
16:03:13 <zodbot> Current chairs: Don Naro samccann
16:03:25 <samccann> General run of the meeting - We go over action items, give docs updates.. maybe have a topic or two, and go over doctooling updates (all the fun stuff behind the scenes that get us docs.ansible.com!)
16:03:44 <samccann> #chair felixfontein
16:03:44 <zodbot> Current chairs: Don Naro felixfontein samccann
16:03:56 <samccann> briantist: around to talk docs today?
16:04:09 <oranod> felixfontein: https://www.tripadvisor.ie/Attraction_Review-g188113-d542816-Reviews-James_Joyce_s_Grave-Zurich.html
16:04:17 <felixfontein> he said he's travelling, but maybe he's around
16:04:28 <samccann> heh docs... and travel tips!
16:04:53 <oranod> I know all the good graveyards in Europe
16:05:01 <samccann> Official agenda is https://github.com/ansible/community/issues/643#issuecomment-1323986744
16:05:10 <samccann> oh fun! in a macabre sort of way
16:05:50 <samccann> felixfontein: did you want to go over your two antsibull-docs PRs that you added to the agenda this week?
16:06:00 <felixfontein> sure :)
16:06:08 <samccann> if the meetup allows :-)
16:06:13 <felixfontein> the first one is already merged since you approved it, so it's just one left ;)
16:06:28 <felixfontein> it was just doors opening at 17:00 (i.e. 6 minutes ago)
16:06:50 <felixfontein> #topic Improve environment variable handling
16:06:51 <felixfontein> #link https://github.com/ansible-community/antsibull-docs/pull/73
16:07:41 <felixfontein> this PR does two things: 1) it uses correct RST formatting (:envvar: role) for environment variables, 2) it adds an index of all environment variables (that are not defined in the core config)
16:08:11 <samccann> so I love it and that it's hotlinked!
16:08:22 <felixfontein> I started with 1) and then noticed that 2) is needed, since :envvar: is basically a reference to the corresponding `.. envvar::` directive
16:08:41 <felixfontein> oh, there was a third part: 3) allow to declare env variable fallbacks for module arguments
16:08:43 <samccann> but the colors aren't obvious that it's a hotlink to that index page entry. Is that a theme thing to ask that it be in blue or something so it's at least suggestive of a hotlink?
16:08:50 <felixfontein> but I can take that one out if it is too controversial
16:09:10 <felixfontein> the colors come from the theme / Sphinx itself, and that's already a problem for env variables in core itself
16:09:33 <felixfontein> see for example https://docs.ansible.com/ansible/latest/reference_appendices/config.html#action-warnings, there the env variables are also clickable
16:09:36 <samccann> ok I'll open a theme request on the ansible theme
16:10:09 <felixfontein> that part is very likely inherited from the RTD theme, but should be easy to adjust
16:10:58 <felixfontein> I think the index is nice, but I'm not sure where it should be placed. it cannot be added to the https://docs.ansible.com/ansible/latest/reference_appendices/config.html page since that's autogenerated by some completely different code (part of ansible-core)
16:11:10 <samccann> #action samccann open ansible theme request to change :envvar: output to blue so it is obvioius that it's a hotlink
16:12:04 <samccann> well if that config page is the right place, we can add it there in the code in ansible/ansible.
16:12:26 <felixfontein> what do you think of the markup and of the index (https://ansible.fontein.de/collections/environment_variables.html shows how it looks for some collections, I would expect the one for Ansible to be a lot larger) in general?
16:12:36 <samccann> or we could add it here https://docs.ansible.com/ansible/latest/installation_guide/intro_configuration.html#environmental-configuration
16:12:46 <felixfontein> oh right, we could add a RST include statement. that would be possible.
16:13:33 <samccann> So maybe the next step is to just open an issue in ansible/ansible for these two items? so we don't lose track
16:13:41 <felixfontein> so basically there would be two steps: 1) get the antsibull-docs PR merged and released, 2) bump the antsibull-docs version in core (devel) and update the script for the config page to link / include the new index
16:13:47 <felixfontein> sounds good!
16:13:54 <samccann> Also dunno what #3 was above or who would need to revew it
16:14:27 <samccann> are you up for opening the ansible/ansible docs issue felixfontein when you get a chance?
16:14:31 <felixfontein> another thing is allowing modules to declare the env variable fallbacks for options in the documentation
16:14:35 <felixfontein> BRB, wifi change
16:15:20 <felixfontein> re
16:15:23 * acozine belated joins in
16:15:34 <felixfontein> I was using my phone before, now I'm using the local wifi (just got credentials) :)
16:15:45 <felixfontein> #chair acozine
16:15:45 <zodbot> Current chairs: Don Naro acozine felixfontein samccann
16:16:13 <oranod> hey acozine
16:16:13 <samccann> welcome welcome
16:16:20 <felixfontein> about env variable fallbacks for options in the documentation: we should probably bring it up with core if we want to have it
16:16:51 <felixfontein> I already created a draft PR for ansible-core which supports it in validate-modules and ansible-doc (by adding version_added_collection and friends to it as well), but that likely won't trigger a discussion :)
16:17:11 <samccann> #action open ansible/ansible docs issue to add links to the new collection envvar index page after the next antsibull-docs release
16:17:38 <bcoca> felixfontein: we just discussed that a bit ... i still think its confusing to users, but ship sailed long ago with aws and networking ussing env vars (former directly, latter indirectly via fallbakc)
16:17:48 <felixfontein> I'm mainly afraid that documenting env variables for modules needs a similar approval chain as for semantic markup...
16:18:16 <bcoca> felixfontein: there was an approval chain for semantic markup?
16:18:23 <samccann> hhmmm...
16:18:30 <felixfontein> bcoca: ah, ok. I agree with the confusing part, especially since users not always understand where and how modules are executed and thus which env variables are available.
16:18:42 <samccann> bcoca yeah, and it failed (aka is just sitting in someone's queue somewhere, dying of neglect)
16:18:50 <felixfontein> bcoca: basically all docs consumer projects seem to have to approve JSON docs output changes...
16:19:15 <felixfontein> though I would hope that most consumers will simply ignore things they don't understand
16:19:15 <samccann> felixfontein: can you elaborate on how this would impact GalaxyNG docs display?
16:19:15 <bcoca> samccann: didnt know we even had a chain nor whom the links are ...
16:19:26 <samccann> ah okay so it's a json docs output change
16:19:33 <bcoca> felixfontein: right now everything needs everyone's approval/nonveto
16:19:41 * samccann cries river of tears
16:19:43 <felixfontein> samccann: it really depends on their code. if their code behaves like antsibull-docs and prints errors/warnings if unknown fields are found, they are affected. if they simply ignore it, they are fine.
16:19:55 <felixfontein> bcoca: which is horrible :)
16:19:56 <bcoca> samccann: you are main consumer of json docs output ... but also galaxy and lint now
16:19:59 <bcoca> and lsp ..
16:20:02 <samccann> bcoca: yeah, it's a busted chain for sure
16:20:04 <bcoca> and ... probably forgetting someone
16:20:20 <bcoca> felixfontein: welcome to my world ... i used to 'just do it' ...
16:20:29 <felixfontein> docsite / antsibull-docs and ansible-lint / vscode are easy to adjust (I know where their schemas live :D )
16:20:35 <samccann> yeah. that's a river of tears kind thing. Can you back that out of this pr felixfontein ?
16:21:03 * bcoca walks away and schedules extra hour for crying in corner
16:21:16 <felixfontein> samccann: we could also allow it in antsibull-docs, to prevent errors printed there if someone use it, but not allow it in ansible-test validate-modules, which basically means that nobody will use it
16:21:24 <samccann> the gist of it is, we have no real way to approve changes to the JSON output so we are stuck with it stagnating
16:21:28 <felixfontein> bcoca: I feel with you!
16:21:42 <samccann> hahah yep
16:22:10 <felixfontein> I'll probably move it to a separate PR, so I can sneak it in ;)
16:22:38 <felixfontein> it would also be nice to document module option deprecations, or other stuff like mutually exclusive / required_if / ...
16:22:41 <samccann> yeah still sounds like a separate PR would be better
16:22:51 <samccann> heh
16:22:52 <samccann> actually thinking out loud
16:22:58 <felixfontein> (actually there was a PR for that 'recently' from the network team I think...)
16:23:04 <bcoca> felixfontein: have you seen my pr?
16:23:13 <felixfontein> bcoca: which one? you have multiple ones :)
16:23:17 <samccann> if you are changing just antsibull-docs right now, that has no impact anywhere else, right?
16:23:26 <samccann> it's only if you make a similar change in ansible/ansible that it has to be approved by everyone and their mother's uncle
16:23:27 <acozine> +1 for separate PRs, that makes each one easier to assess and (with luck) shepherd along
16:23:36 <bcoca> im down to 56! ... been good about that ...
16:23:59 <samccann> heh
16:24:01 <felixfontein> samccann: exatly, except that someone can start using by simply ignoring the ansible-test validate-modules errors...
16:24:10 <bcoca> https://github.com/bcoca/ansible/tree/controller_argspec  trick question, it wqas branch
16:24:15 <felixfontein> bcoca: https://github.com/ansible/ansible/pulls/bcoca says 54
16:25:07 <bcoca> felixfontein:  i have 2 against non ansible projects ...
16:25:27 <felixfontein> bcoca: ah, you were talking about all PRs you have, not just ansible/ansible ones :)
16:25:41 <bcoca> i'v set 60 as my limit
16:26:31 <felixfontein> I don't have a limit, but I think I try to have a lot less
16:26:37 <felixfontein> but then I also don't work fulltime on this :)
16:27:23 <bcoca> go back to docs, thsi is starting to sound like my therapy session ...
16:27:30 <felixfontein> :D
16:27:50 <felixfontein> ok, so to sum up, the general idea is good, we still have to figure out where exactly to place the index, and how to name that file
16:28:08 <felixfontein> I'll probably start with an experimental ansible/ansible PR that includes that file in the docsite
16:28:36 <felixfontein> if anyone has ideas / suggestions / improvement / other comments, please add them to the PR(s) :)
16:28:42 <samccann> cool thanks!
16:29:14 <felixfontein> thanks everyone :)
16:29:33 <felixfontein> I'll head off to the apero now, enjoying the meetup ;)
16:29:38 <samccann> Thanks felixfontein !!
16:29:39 <samccann> #topic Documentation updates
16:29:54 <felixfontein> #unchair felixfontein
16:29:54 <zodbot> Current chairs: Don Naro acozine samccann
16:29:57 <samccann> thanks! have fun!
16:29:57 <acozine> Enjoy felixfontein !
16:30:01 <felixfontein> thanks!
16:30:55 <samccann> #info Ansible 7 released last week w/ docs!
16:30:57 <samccann> #info Archived 2.4 docs - redirects are live now.
16:30:57 <samccann> working on 2.5 now
16:31:08 <samccann> Do we have other general docs updates today?
16:31:27 * samccann hasn't fully recovered from eating too much pie last week
16:31:34 * acozine hasn't fully recovered from Covid
16:32:11 <samccann> ooch. yeah, that's a different sort of recovery!
16:32:37 <oranod> yikes. hope you get back to 100% soon acozine
16:33:29 <acozine> thanks, I am taking it slow, today is my first day back at the keyboard
16:35:05 <samccann> and you share it with us.. woot!
16:35:10 <acozine> sadly, it also means I don't have much to say
16:35:19 <samccann> me either this week.
16:35:22 <acozine> but i enjoy the camaraderie
16:35:32 <samccann> cups of 🍵for all!
16:35:41 <samccann> and a 🍪
16:36:36 <samccann> ok I've digressed quite a bit lol!
16:36:38 <acozine> heh
16:36:43 <samccann> #topic Open Floor
16:36:43 <acozine> are there any open PRs we should look at?
16:37:01 <acozine> oh, how did the release turn out in the end?
16:37:05 <samccann> since I've run out of steam today. anyone have docs thoughts to talk about?
16:37:37 <oranod> I guess we could mention the fact the docsite repo will be public later this week
16:38:03 <samccann> woo hoo!!!
16:38:07 <oranod> #info the plan is to make the ansible/docsite repo, which has the html fragements for docs.ansible.com, public
16:38:26 <acozine> ooh, that is great news!
16:38:43 <acozine> now we can have multiple sets of eyes on all those pesky redirects
16:38:48 <oranod> yes!
16:38:57 <oranod> the redirects as well as the layout and navigation
16:39:23 <oranod> I think it'll be great to tie into the personas that samccann is working on too (and will also bring to the community)
16:39:38 <samccann> yep for sure
16:39:50 <samccann> will be a funfilled few months in docs land!
16:40:33 <samccann> as for PRs to review - https://github.com/ansible/ansible/pull/79221
16:40:39 <samccann> mostly the comment on the proposed output
16:41:09 <samccann> https://github.com/ansible/ansible/pull/79221#issuecomment-1329363454 for a direct link
16:41:31 <samccann> The table is great but quite wide. So i tried shrinking 3 columns into 1 and would like feedback on whether it works or not
16:41:53 <samccann> this is the original table in the PR - https://github.com/ansible/ansible/pull/79221#issuecomment-1293939886
16:42:28 <oranod> ooof. are those footnote links in table cells?
16:44:18 <samccann> yes
16:44:30 <samccann> they show up below the table (tho not great, it's a theme problem)
16:45:38 <oranod> yeah... that's a pretty big accessibility no no
16:46:38 <oranod> I can take a look and offer an alternative but just wanted to point that out
16:47:04 <oranod> that one always stands out to me because I have a friend who uses a screen reader and absolutely hates those lol
16:47:50 <samccann> ah good to know!
16:48:44 <samccann> and I have the PR locally with the updated table so I can implement whatever you suggest for the footnotes.
16:49:55 <samccann> this new docs issue is a fun one - https://github.com/ansible/ansible/issues/79482
16:50:18 <samccann> edit on github disappeared from some pages after the user guide restructure
16:50:52 <oranod> oh no
16:50:52 <samccann> I haven't looked at the details yet to see why that might be. I know we have 'exceptions' in the code that controls this. My guess is some of these new pages hit one of those exceptions. but I could be out in space on that one
16:52:21 <acozine> hm, that's weird
16:53:50 <samccann> ok we have a few minutes left. any other topics?
16:56:12 <oranod> just thinking out loud here but I did a talk in Dublin last week that focused on docs, more specifically about being a content developer working on a devOps team. I wonder if there's a way to share that with the community here?
16:56:23 <oranod> might be something to get a docs convo going, etc
16:56:27 <samccann> by content developer, do you mean someone like felix... or a writer?
16:57:22 <oranod> in my mind a content developer is kind of writer + creating tools and stuff to make docs available
16:57:41 <oranod> so probably more like what felix is doing
16:58:15 <samccann> ok. We should talk to greg and see if there's a way to do a video here, then just pick a day/time and put it in the bullhorn
16:58:44 <samccann> but I like the idea of having a presentation (especially when I'm not presenting :-)
16:58:55 <oranod> yeah that sounds fine. it might not really even be worth it but just a thought.
16:59:01 <acozine> maybe next contrib summit?
16:59:12 <oranod> although I honestly hate the idea of recording myself on video
16:59:24 <samccann> well I'm thinking it would be nice to have it sooner/less formal etc
16:59:58 <oranod> perhaps then too acozine but I guess it isn't too specific to ansible at the same time
17:00:16 <acozine> ah, gotcha
17:00:29 <samccann> Ok we're about at time again
17:00:49 <samccann> #endmeeting