15:01:31 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:31 <zodbot> Meeting started Tue Oct 19 15:01:31 2021 UTC.
15:01:31 <zodbot> This meeting is logged and archived in a public location.
15:01:31 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:31 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:31 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:37 <samccann> #topic opening chatter
15:01:38 <briantist> o/
15:01:45 * acozine waves
15:01:46 <samccann> so... who's around to talk the docs today??
15:01:55 <samccann> #chair acozine briantist
15:01:55 <zodbot> Current chairs: acozine briantist samccann
15:02:05 <samccann> welcome welcome!
15:03:03 <samccann> andersson007_ dericcrago dmsimard gundalow tadeboro cyberpear felixfontein mrproper[m] Xaroth ariordan you folks chatting docs today?
15:03:21 * acozine goes to grab fresh tea, the kettle just boiled
15:03:32 <ariordan> Hi all!
15:03:41 <dmsimard> I'm here but multi-threading right now :D
15:03:51 <briantist> (^same)
15:04:04 <samccann> #chair ariordan dmsimard briantist
15:04:04 <zodbot> Current chairs: acozine ariordan briantist dmsimard samccann
15:04:32 <samccann> no worries. we'll welcome any spare threads you can send our way today ;-)
15:05:34 <samccann> #info agenda at https://github.com/ansible/community/issues/579#issuecomment-945632120
15:05:45 <samccann> #topic action item review
15:06:25 <samccann> So my brain is still not quite engaged after vacation, but I can safely say I haven't done anything since last meeting :-)
15:06:25 * acozine is back and fortified with tea
15:06:31 * dericcrago waves
15:07:15 <samccann> #chair deric.crago
15:07:15 <zodbot> Current chairs: acozine ariordan briantist deric.crago dmsimard samccann
15:07:54 <samccann> ariordan: - any update on changing the boilerplate text on each collection module page?
15:08:27 <acozine> we did talk about that last week
15:08:56 <acozine> about how the fragment could be used in collections that are not in the Ansible package
15:09:14 <samccann> oh there's a merged pr -  https://github.com/ansible-community/antsibull/pull/318
15:09:17 <samccann> maybe that action item is done?
15:09:48 <acozine> yerg
15:10:01 <acozine> I would have voted against that PR
15:10:26 <samccann> PRs welcome if you want to tweek it a bit :-)
15:10:30 <acozine> heh
15:11:03 <acozine> I think it needs logic for "if this is getting published to docs.a.c"
15:11:13 <acozine> not all collections are included in Ansible the package
15:11:21 <acozine> but all collections can use antsibull
15:11:31 <samccann> I'm fuzzy on where this is used outside of docs.ansible.com tho
15:12:06 <acozine> some collection maintainers build their own docsites, don't they?
15:12:27 <acozine> IIRC at least some of tadeboro's clients do that
15:12:38 <acozine> and I think they use the antsibull tools
15:12:47 <samccann> but how would antsibull know whether it was being run for docs.ansible.com or for 'someplace else'?
15:13:25 <acozine> it's currently a bit of an edge case, though, so maybe it doesn't matter so much for now
15:13:27 <ariordan> What kind of logic would we need for this? I was trying to figure this out after last week's meeting, and then noticed that the PR got merged. I should have changed it to [WIP], apologies.
15:14:07 <ariordan> Could we just do another re-wording for now?
15:14:37 <samccann> not clear how we'd reword it.
15:15:09 <samccann> 90% of the time it would be correct. If we add text to say 'check docs.ansible.com' it will be a referrential loop so to speak ;-)
15:15:46 <acozine> maybe something like "You may already have this collection installed if you are using the ``ansible`` package. To check, run `ansible-galaxy collection list`. If it is not installed, you can install it with: "
15:15:58 <acozine> and then pick up the existing wording?
15:16:07 <acozine> that may not be the right ansible-galaxy command
15:16:11 <acozine> but i know there is one
15:16:22 <ariordan> That should cover it.
15:17:19 <acozine> oh, and s/may/might
15:17:26 <tadeboro> I am in a meeting right now, but I noticed my nick pop up. We are generating our own webdocs for sensu go (https://sensu.github.io/sensu-go-ansible/), but we are not using antsibull (we use custom tooling that predates antsibull - we had to have docs ready when the Ansible 2.9 was just out of the oven ;)).
15:17:47 <samccann> yeah that sounds good.
15:18:11 <samccann> you okay to give that a try ariordan ?
15:18:28 <ariordan> Yes, I'll do that.
15:18:32 <acozine> the ansible-galaxy might also include version info
15:18:37 <acozine> that's another use case
15:18:46 <felixfontein> o/
15:18:51 <acozine> "Ansible installs version 3 but I need version 4 of this collection"
15:19:12 <samccann> #chair felixfontein
15:19:12 <zodbot> Current chairs: acozine ariordan briantist deric.crago dmsimard felixfontein samccann
15:19:13 <samccann> welcome!
15:19:35 <samccann> i think we're getting kinda verbose now
15:19:56 <samccann> 90% of the people don't need this info at all but we are ramming it down their gobs anyway.
15:20:04 <acozine> yeah, true
15:20:54 <samccann> But I like the rewording etc with the galaxy command to find out if you have it. Let's see how that looks.
15:21:32 <samccann> #action ariordan to reword boilerplate text on collection module page to something like You may already have this collection installed if you are using the ansible package. To check, run ansible-galaxy collection list. If it is not installed, you can install it with:
15:21:51 <samccann> ok any other action items before we move on?
15:22:10 <felixfontein> sorry for merging that PR too early!
15:22:35 <acozine> no worries, I should have put a comment on the PR directly, and i didn't
15:22:46 <acozine> iterative improvement
15:24:13 <samccann> #topic Felixfontein's items
15:24:37 <samccann> :-) I see you have three comments added to the Agenda this week. Is there commonality or should we just take one at a time?
15:24:42 <felixfontein> now I have actually to check because I don't remember what I put on the agenda anymore ;)
15:24:49 <samccann> felixfontein: ^^
15:25:05 <felixfontein> I think they are independent of each other
15:25:25 <felixfontein> and one is in fact a PR of baptistemm :)
15:25:26 <samccann> ok we can start at the top
15:25:41 <samccann> #link https://github.com/ansible-community/antsibull/pull/319
15:25:56 <samccann> Do you want to give a bit of background on that one?
15:26:04 <felixfontein> I guess the main question for that one is whether it looks good that way
15:26:20 <felixfontein> so far `choices` was only available for module/plugin parameters, but not for return values
15:27:12 <felixfontein> while antsibull validated choices for return values, it never rendered them. and ansible-test only recently allowed choices in return values. (they are docs only, as there's no mechanism to validate return values against the return value documentation.)
15:27:51 <felixfontein> the intend is to make it easier to tell users "this return value is one of the following constants" instead of "this is a string, and we have to mention in the documentation text which values are possible, and that only these values can be returned"
15:28:09 <acozine> it feels weird to call return values "choices", because you can't choose them
15:28:27 <felixfontein> true :)
15:28:31 <acozine> maybe "possible values" or something?
15:28:43 <samccann> options?
15:28:46 <felixfontein> hmm, "possible values" sounds somewhat close to "examples" IMO
15:28:55 <samccann> or does that get confused with module options/parameters?
15:28:56 <felixfontein> maybe "All values that are possible:"?
15:29:13 <samccann> possible return values?
15:29:41 <acozine> or a phrase like "can only return:"?
15:29:46 * samccann pulls out her fav colors... let the wordsmith bikeshedding commence!!
15:29:50 <felixfontein> 'possible' to me indicates that these are values that are returned, but not that these are *all* that can be returned (and there are no others)
15:29:53 <acozine> heh
15:30:22 <felixfontein> 'Can only return:' sounds good to me
15:30:24 <samccann> can only return sounds like a good candidate then
15:30:31 <samccann> JINX!
15:30:41 <samccann> you owe me a soda!
15:31:01 <samccann> or your local fizzy equivalent ;-)
15:31:02 <felixfontein> :)
15:31:20 <felixfontein> if you ever visit, I'll provide you with something like that ;)
15:31:30 <samccann> acozine: do you want to put that as a suggested edit/comment in the pr?
15:31:36 <acozine> sure
15:31:49 <samccann> what country are you in again? I should know this by now but my brain is still on vacation
15:32:33 <samccann> #link https://github.com/ansible-community/antsibull/pull/320
15:32:42 <samccann> skipping to your other one felixfontein
15:33:18 <felixfontein> samccann: switzerland!
15:33:22 <felixfontein> acozine: samccann: thanks!
15:33:42 <acozine> https://github.com/ansible-community/antsibull/pull/319#issuecomment-946844842 - comment added
15:33:47 * samccann books tix for swiss soda
15:33:55 <samccann> cool thanks acozine
15:35:04 <samccann> felixfontein: PR LGTM but can you post a test output so we know the logic works?
15:35:07 <felixfontein> that one is an improvement for the ansible.builtin disclaimer, which currently always says 'module' for all kind of plugins as well
15:36:11 <acozine> so PR 320 limits that note to modules but doesn't add anything for non-module plugins?
15:36:19 <acozine> that's an improvement
15:36:33 <acozine> do we want something to appear for non-modules in future?
15:36:34 <felixfontein> acozine: it doesn't limit it; it prints `<plugin type> plugin` for plugins, and `module` for modules
15:36:57 * acozine reads it again
15:37:03 <samccann> :-)
15:37:09 <acozine> ah, yes, there's an `else` in there
15:37:20 <acozine> jeez, maybe I needed more caffeine today
15:37:28 <acozine> looks good to me
15:37:34 <samccann> tea hasn't had time to reach your bloodstream yet!
15:37:52 <felixfontein> see https://ansible.fontein.de/t/collections/ansible/builtin/add_host_module.html#ansible-collections-ansible-builtin-add-host-module vs https://ansible.fontein.de/t/collections/ansible/builtin/runas_become.html#ansible-collections-ansible-builtin-runas-become
15:38:25 <felixfontein> and compare to https://docs.ansible.com/ansible/latest/collections/ansible/builtin/runas_become.html
15:39:18 <samccann> LGTM
15:39:30 <samccann> I can put an approval on the PR but it needs a coder to check the logic
15:40:22 <acozine> one nit
15:40:38 <acozine> the module/plugin name appears in plain text, not in `code`
15:40:55 <acozine> As in: In most cases, you can use the short module name add_host
15:41:19 <felixfontein> true. that has been like that before already though :)
15:41:22 <samccann> fwiw that's an existing problem
15:41:32 <acozine> heh
15:41:34 <felixfontein> I can add a fix to the PR though
15:41:41 <samccann> i'm cool if it can be added to this PR or just a separate issue/pr if we think it can be fixed
15:42:13 <felixfontein> I pushed a commit to the PR
15:42:30 <samccann> that was fast!
15:42:42 <acozine> awesome
15:42:48 <felixfontein> it's an easy fix :)
15:43:07 <acozine> it's so much easier to find those things when you're changing neighboring code/wording
15:43:33 <acozine> thanks felixfontein
15:43:56 <samccann> #link https://github.com/ansible-community/antsibull/pull/296
15:44:12 <samccann> baptistemm: are you around to discuss this pr?
15:44:31 <samccann> (I'm guessing bad time, but figured i'd try the ping anyway)
15:45:41 <acozine> Borders certainly can be ugly, but they can also be useful, especially when you don't know the size of the user's screen.
15:46:12 <felixfontein> meh. looks like I posted file:/// links :)
15:46:24 <samccann> just noticed that felixfontein lol
15:46:41 <acozine> Lots of testing on phones/tablets for this PR
15:46:45 <samccann> not sure how the border lines help for screen sizes?
15:47:26 <samccann> it is still a table. which is problematic on a phone anyway, unless it converts to a list? I thought someone had that magic working somewhere?
15:47:48 <felixfontein> I've updated the links (and rebuild the site so that branch is used again)
15:48:13 <felixfontein> samccann: I wanted to work to table -> list at some point, but didn't got around to do that yet
15:48:50 <ariordan> I think borders help when the content fills the columns.
15:49:17 <samccann> that's my point tho, ariordan I think there is always 'space'
15:49:26 <samccann> tho that space no longer has a line through it.
15:50:20 <ariordan> Yes. I prefer a light / thin border (like what we have now). But it's just a personal preference.
15:51:06 <felixfontein> I'm +-0 on borderless, but I like the coloring
15:51:41 <samccann> ok I tried it on my phone with felix's links. It looks ..kind of like it looks if you just shrink your browser way down
15:51:51 <felixfontein> acozine: I've updated the formulation in #319
15:52:23 <felixfontein> samccann: yeah, that should be similar to how it looks at the moment, with borders and without colors :)
15:52:38 <samccann> there is a sizable space between columns and the differing shades between rows make it easier to see
15:53:27 <samccann> i'm also neutral on the border but like the alternately shaded rows for sure
15:54:00 <samccann> We have 8 minutes left. Do we ask for the lines back or keep it as is and try it out on a few browsers to be sure?
15:54:59 <acozine> Can someone build it to the testing site?
15:54:59 <ariordan> +1 for the alternately shaded lines.
15:55:05 <acozine> or is it there already?
15:55:30 <samccann> it's a combination of prs. I don't know how to build it to test
15:55:49 <felixfontein> samccann: it's only one PR (at the moment)
15:55:53 <samccann> can we use Felix's builds to test?
15:56:18 <samccann> ok I put a comment in there ages ago that I don't know how to build it locally
15:56:34 * acozine scrolls down
15:56:40 <samccann> if you can add details to the PR on how to do that, I can give it a whorl
15:57:19 <samccann> I'd have to hack the jenkins build to pull in that PR version of antsibull, right?
15:57:23 <felixfontein> I don't really know how that works with jenkins
15:57:43 <samccann> right now it's a pip install foo
15:58:01 <samccann> so how would I do pip install foo-from-pr is the question.
15:58:07 <felixfontein> you probably have to install antsibull from that branch, instead of installing it as a regular package
15:58:15 <felixfontein> let me check
15:58:25 <acozine> I'm +1 on the alternating colors but not having lines between the columns looks a bit odd to me
15:58:27 <samccann> yeah that's the bit I don't know how to do, especially within jenkins
15:58:37 <acozine> yikes, sorry, I need to run
15:58:43 <acozine> I'll put a comment on the PR
15:58:47 <samccann> ok thanks acozine
15:59:00 <felixfontein> pip install https://github.com/bmillemathias/antsibull/archive/borderless-module-option-table.tar.gz
15:59:03 <felixfontein> that should work
15:59:04 * acozine waves
15:59:06 <felixfontein> bye acozine!
15:59:07 <acozine> #unchair acozine
15:59:07 <zodbot> Current chairs: ariordan briantist deric.crago dmsimard felixfontein samccann
15:59:12 <samccann> #info consensus is the alternating row colors is great but some people miss the border lines.
15:59:26 <samccann> #info to test this locally - pip install https://github.com/bmillemathias/antsibull/archive/borderless-module-option-table.tar.gz
15:59:47 <felixfontein> I can re-add the border lines if we want them back
15:59:54 <samccann> #action samccann to try the border shading PR locally and on jenkins so we can test with multiple browsers, on phones/tablets etc
16:00:37 <samccann> Let me screencap from your website with no border lines first. Then yeah, might help to add them back and we can compare
16:00:51 <samccann> we are at the top of the hour. so
16:00:56 <samccann> #topic OpenFloor
16:01:14 <samccann> if anyone lingered this long and would like to bring something up, please do!
16:02:17 <ariordan> I'm creating a few more Hacktoberfest issues.
16:02:59 <briantist> the only thing I have is the (to me, inconsistent) handling of the RST refs generated by `seealso:` section's `module:` and `ref:` options. If you have history, I brought it up in more detail above.
16:02:59 <samccann> cool! they seem to be a hit!
16:03:22 <briantist> But basically, the refs are all trying to resolve to Ansible 4 docs, and since some of the refs don't exist there yet, they are failing.
16:03:40 <felixfontein> briantist: I couldn't find any details in what you wrote. what exactly is strange?
16:04:33 <samccann> briantist: thanks. I'm not sure how that all works either, really. :module: 'seems' like it depends on intersphinx links. Maybe R(foo) just has code to change the R to :ref: in the rst, and thus acts like any other rst ref
16:04:35 <briantist> what I described just above: the refs aren't working because they are trying to render links to the public docsite, not the local docsite being generated. But `R(link text,rst ref)` works/renders correctly. And I can't find any different in the intermediate RSTs.
16:04:38 <felixfontein> briantist: if you provide `ref:` it will simply be converted into a :ref:`...` directive
16:04:53 <felixfontein> briantist: if the refs don't work, it's probably related to your docs build
16:05:31 <samccann> what breaks is the :module: when using it to reference a new module that isn't on the docsite
16:05:43 <samccann> for some reason, that doesn't go local, it goes to docs.ansible.com I think?
16:05:53 <samccann> where of course the new module doesn't exist
16:06:02 <felixfontein> what is :module: ? do you mean `module:` in `seealso`?
16:06:05 <briantist> felixfontein: I assume that it is indeed related to my docs build! But I can't figure out what is wrong with it. I use the stuff generated by the docs init.
16:06:07 <felixfontein> or `M(...)`?
16:06:27 <briantist> yes, in `seelaso:` both `module:` and `ref:`.
16:06:38 <briantist> `R(...)` works as expexted.
16:07:04 <briantist> It's possible to pull down the PR or my branch from here: https://github.com/ansible-collections/community.hashi_vault/pull/156
16:07:24 <briantist> and run `docs/preview/build.sh` to see the warnings it emits and the resulting html
16:10:37 <briantist> in this example, the top link renders in my local build, but renders to the public docsite. Bottom ref does not exist publicly yet (it's in this PR), so it does not render. https://www.irccloud.com/pastebin/se66An5s/
16:12:01 <briantist> meanwhile my use of `R(...)` in the `requirements:` section for example, makes a `:ref:` like this, which works fine and points to the local docs correctly https://www.irccloud.com/pastebin/LNiF8xuH/
16:12:53 <felixfontein> briantist: there's at least one bug in your PR, I've added a comment
16:13:26 <samccann> ok we are 13 min over so I'll close out  the meeting and we can continue to discuss the refs problems
16:13:50 <samccann> #endmeeting