15:00:57 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:57 <zodbot> Meeting started Tue Jul 19 15:00:57 2022 UTC.
15:00:57 <zodbot> This meeting is logged and archived in a public location.
15:00:57 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:57 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:57 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:06 <samccann> #topic opening chatter
15:01:20 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:23 <DonNaro[m]> o/
15:01:34 <samccann> #chair Don Naro
15:01:34 <zodbot> Current chairs: Don Naro samccann
15:01:36 <DonNaro[m]> hi samccann only half here (as usual)
15:01:43 <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!
15:02:01 <samccann> well could be you, me, and the bots today!
15:02:33 <samccann> briantist: felixfontein you around to chat docs today?
15:02:47 <briantist> o/
15:02:56 <samccann> ahoy!
15:02:57 <briantist> in another meeting but sorta here..
15:03:00 <samccann> #chair briantist
15:03:00 <zodbot> Current chairs: Don Naro briantist samccann
15:03:18 * samccann bluck... does not like her new coffee
15:03:58 <samccann> ok let's get started
15:04:01 <samccann> #topic Documentation Updates
15:04:32 <samccann> briantist: I can't recall if you were part of the discussion on whether to move the windows dev guide out to a collection?
15:05:02 <samccann> I feel like that resolved into 'don't move it' because it's mostly focused on either core or generic to any collection that needs to support windows?
15:05:16 <samccann> #link  https://github.com/ansible-collections/community.windows/issues/394 and https://github.com/ansible/community/issues/643#issuecomment-1180358267
15:05:50 <briantist> I was yeah
15:06:13 <briantist> and yes, I believe we've basically reached a consensus of don't move it
15:06:26 <samccann> ok cool
15:06:46 <briantist> if there were things that were specific to `c.w` or `a.w` they should go into guides in those collections, but there are no such items that I know of
15:07:19 <samccann> #agreed do not move the windows developer guide to a collection. It's more generic and belongs where it is
15:07:20 <briantist> everything in the guide is relevant to the core of ansible (whether there are windows modules in core or not)
15:08:45 <samccann> cool thanks!
15:08:46 <samccann> I closed the issue
15:08:46 <samccann> #info - if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.
15:09:14 <samccann> just a general reminder for folks that we have community-writers eager to help out and it doesn't have to be ansible/ansible. They can provide editoral help on collection level docs or any other ansible-related project.
15:10:24 <samccann> #topic doctools
15:10:44 <samccann> #info - redirects based on referrers to redirect old EOL docs to latest seem to work - https://hackmd.io/0B7n-FUySF6MB3CQeaqUkA?view
15:11:16 <samccann> #info this may solve our problems with external search results picking up very old EOL docs within the top few results
15:11:48 <samccann> to explain - searching for some ansible things can bring up a 2.3, 2.4 doc as first or second results. This pushes traffic to these very old docs.
15:12:30 <samccann> so we initially talked about moving them to an archive site, but spredzy (dunno if he's got an alias) came up with a way to use redirects with a check on the referrer. Details up on that hackmd
15:13:08 <samccann> but redirecting one page worked. I can generalize from there but I'm asking our internal search expert to be sure there aren't other problems here before we move forward
15:14:54 <samccann> last week we agreed to back out the boolean override so gonna meeting minute it this time
15:16:01 <felixfontein> o/
15:16:01 <samccann> this was the case where docs forced the documentation to always say `yes/no` instead of whatever the collection owner had for the boolean parameter.
15:16:02 <samccann> the debate is still pending on what to do about `ansible-lint` wanting everything true/false etc. But at least it pulls the docs override out of that debate.
15:16:51 <samccann> #info Looking for ideas on how to get CI testing to work on rst pages excluded from ansible-core (what ansible/ansible CI covers today) - Please comment on https://github.com/ansible-community/community-topics/issues/111
15:17:20 <felixfontein> what exactly do you mean with "back out the boolean override"?
15:17:29 <felixfontein> change yes/no to true/false?
15:17:31 <samccann> ^^ this one has to do with the fact we have two docsites and we exclude a bunch of rst files from the core docsite for good reasons (collection stuff). But it means the ansible/ansible docs CI is excluding those files as well.  So.. open to ideas etc
15:17:58 <samccann> I think my first try is to create a `make rst-all` or something that includes all the rst files and see what that does
15:18:08 <samccann> #chair felixfontein welcome welcome!
15:18:08 <zodbot> Current chairs: Don Naro briantist felixfontein samccann welcome welcome!
15:18:32 <samccann> we're just fryin some docs on the griddle here!
15:19:00 <samccann> griddle? grill? honestly not sure what a griddle is.. I think I was channeling an old radio song
15:19:26 <briantist> griddle is a flat heated surface (no slats or openings into the heat source)
15:19:28 <felixfontein> at least my dictionary knows what a griddle is
15:19:44 <briantist> think pancakes 🥞burgers 🍔, etc.
15:19:48 <samccann> I'll have to dig up the actual code, but there is code in ansible/ansible docs generation (or maybe it's in antsibull now?) that says something like - if this is a boolean parameter, list the choices as yes/ no regardless of what's in the module code
15:20:13 <felixfontein> briantist: that's not what my dictionary says, but wikipedia agrees with you ;)
15:20:42 <samccann> yeah that was the song in my head.. I got me a fine life I got my own griddle or something like that
15:20:49 <felixfontein> samccann: true, but then we don't know what's in the module, since we only have the parsed YAML - and there we have boolean values
15:20:51 <briantist> felixfontein: interesting, what does your dictionary say?
15:21:02 <felixfontein> and we need to render them as either true/false, or as yes/no, or as True/False, or ...
15:21:28 <bcoca> samccann: iirc, it is in the jinja2 template that renders those pages (the forced yes/no)
15:21:59 <samccann> ok this is the original pr from back in 2018 - https://github.com/ansible/ansible/pull/36901
15:22:06 <felixfontein> briantist: https://dict.leo.org/german-english/griddle - not that the german word will help you much though ;)
15:22:17 <bcoca> felixfontein: most booleans don't show the options, they are assumed, you can check the BOOLEAN constants in ansible for actual values
15:22:43 <samccann> https://github.com/ansible/ansible/pull/36901/files#diff-b084faabfc6d6ec38de3459882739152a10e5173d5754e50db49ee423afa38eaR110
15:24:11 <felixfontein> samccann: the alternative to that code is to use the default way that booleans are converted to strings by jinja2 / Python, i.e. `True` / `False`
15:24:17 <samccann> so does that code look familiar at all felixfontein ?
15:24:55 <felixfontein> I know that code pretty well, I'm mainly saying that it is not an override "change what the user provided with what we want", but "change what the YAML parser interpreted with what we want
15:26:16 <samccann> hmm okay so let me see if I get this right
15:26:47 <samccann> there isn't a 'default that the coder meant'.  There is only a boolean indication in the code, and WE have to decide if it says yes or true or True?
15:26:57 <felixfontein> bcoca: docs mostly use true/false or yes/no or True/False, only sometimes do they use strings ('yes'/'no')
15:27:09 <felixfontein> samccann: basically yes
15:29:19 <samccann> oh well. guess we can't just 'back out' anything in docsland. We have to wait for resolution to https://github.com/ansible-community/community-topics/issues/116
15:30:04 <samccann> #info for the docs boolean 'override' - it's not an override - there is no 'default' that the cooder meant. There's only the boolean indication in the code and docs has to decide whether it says true, True, or yes.
15:30:17 <samccann> #info must wait for resolution to https://github.com/ansible-community/community-topics/issues/116 before we make any changes.
15:30:30 <samccann> thanks for the explanation.
15:31:16 <felixfontein> we only know what the programmer wanted when they wrote strings instead of booleans, or used 1 / 0 (integers) or other things that ansible converts, but PyYAML does not
15:32:28 <samccann> #topic Open Floor
15:33:09 <samccann> can you explain that last be for me? ansible converst by pyyaml doesn't?
15:33:23 <samccann> does PyYAML display anything like docs does?
15:33:32 <samccann> bcoca: what does `ansible-doc` do?
15:33:49 <felixfontein> ansible converts strings like 'yes' and 'no' to booleans (if it knows that they are passed for boolean parameters)
15:33:50 <bcoca> as little as possible
15:34:07 <felixfontein> PyYAML converts 'yes' and 'no' when it doesn't know they are a string
15:34:12 <bcoca> ^ yaml does, so to show the default, iirc, it just uses true/false
15:34:17 <bcoca> which is what the result is
15:34:21 <felixfontein> so if you use explicit quotes around yes and no, ansible will still convert it while PyYAML does not
15:34:45 <bcoca> we force booleanization on boolean fields, but use same rules as pyyaml (mostly)
15:35:19 <bcoca> but that is on config side, i believe we dont even bother on docs side
15:36:44 * samccann taps keyboard... is this thing on?
15:37:05 <samccann> :-) I can't tell if folks all got busy or if i'm experiencing a big lag between matrix/irc
15:37:26 <briantist> for me? got busy/distracted
15:38:07 <briantist> but I see stuff from bcoca and felixfontein (who are on IRC, same as me), so maybe there is some lag going on?
15:38:29 <bcoca> im in 2 meetings
15:39:02 * samccann whistles into the void
15:39:09 <samccann> Does anyone else have anything to bring up in docsland?
15:39:22 <felixfontein> I'm browsing through some antsibull code a bit, it does some more processing than ansible-doc, but not much
15:39:23 * samccann waits for the opinions of the bots following along :-)
15:39:29 * bcoca suspects the void is staring back
15:41:15 <samccann> yeah just got a fast batch from y'all all at once here in matrix. must be one of the bots is asleep at the wheel.
15:42:22 <bcoca> feed the internet gerbils!
15:42:46 <samccann> hehe
15:43:01 <samccann> so yeah, docs and `ansible-docs` should show the same thing.
15:43:12 <samccann> for booleans.
15:43:28 <samccann> And in the perfect world, so would AH/Galaxy-ng
15:43:44 <bcoca> im not too hung up on that, yes/no true/false are not that hard to grasp
15:44:04 <felixfontein> ansible-doc shows True/False currently, ansible-lint wants true/false, docs.ansible.com shows yes/no
15:44:06 <bcoca> that one shows one vs the other ... not that big of a deal imho, unless one version did not work .. which is not hte case
15:44:22 <bcoca> what ansible-lint wants ....
15:44:27 <felixfontein> :)
15:44:33 <samccann> well we do have hyea, what ansible-lint wants
15:44:36 <felixfontein> just listing it since its wishes sparked this discussion...
15:44:51 <samccann> which is part of the ansible ecosystem. So ideally, we find consistency.
15:44:58 <felixfontein> TBH I also prefer true/false, but NOT because ansible-lint wants it :D
15:45:14 <samccann> there was something I thought about YAML 1.2 requiring true/false? is that real or did I dream that one up?
15:45:17 <bcoca> i prefer 0/1 .. but im not going to fight on this one
15:45:24 <bcoca> on/off ... for certain cases
15:45:36 <felixfontein> oh right, almost forgot about on/off
15:45:52 <bcoca> samccann: but we are no 1.2, still 1.1 and pyyaml does not seem close to implementing 1.2
15:46:01 <samccann> heh
15:46:22 <bcoca> rephrase: they have been close to 1.2 for 4yrs now ...
15:46:23 <felixfontein> 1.2 is the reason ansible-lint prefers true/false (or at least they now say so)
15:46:42 <felixfontein> at least they have progress, as opposed to goyaml...
15:47:07 <bcoca> even a valid 1.2 parser should only use 1.2 syntax if the % YAML 1.2 pragma is used in the doc ... soo i would say lint shoudl first check for that
15:47:43 <bcoca> felixfontein: why at this point i assume 1.2 does not exist, nor will it exist in my lifetime
15:47:45 <samccann> #info YAML 1.2 requires true/false but ansible is still on 1.1 and pyyaml hasn't implemented YAML 1.2 for the past 4 yrs or so
15:48:33 <bcoca> iirc, ruamel is only one that does implement 1.2 but still not good enough imho
15:48:43 <samccann> there was an updated comment about this I just saw - https://github.com/ansible-community/community-topics/issues/116#issuecomment-1189003045
15:48:51 <felixfontein> bcoca: I don't make any assumptions on it, except that I also cite it to have a more rational reason than "I just like this more" :)
15:49:15 <bcoca> python does not use true/false, it uses True/False
15:49:22 <bcoca> so it alligns with JSON, but not python
15:50:10 <felixfontein> bcoca: I was about to say that...
15:50:21 <bcoca> also, neither json nor ptyhon parsing taskes care of these issues, onlyl YAML and jinja2 do conversions in ansible
15:50:30 <bcoca> and they both 'agree' on the full 1.1 yaml boolean set
15:51:11 <felixfontein> with jinja2 you mean some Python code in ansible/ansible that does that?
15:51:25 <felixfontein> (probably somewhere in Templar)
15:51:28 <bcoca> our jinja2 templating uses BOOLEANS_TRUE/FALSE to do conversions
15:51:30 <bcoca> yes
15:51:54 <felixfontein> which for the end user looks the same, until they start using jinja2 in other contexts :)
15:52:05 <bcoca> ansible.module_utils.parsing.convert_bool < also built into argspec
15:52:12 <bcoca> felixfontein: yep
15:52:29 <bcoca> lib/ansible/module_utils/parsing/convert_bool.py:BOOLEANS_TRUE = frozenset(('y', 'yes', 'on', '1', 'true', 't', 1, 1.0, True))
15:52:30 <bcoca> lib/ansible/module_utils/parsing/convert_bool.py:BOOLEANS_FALSE = frozenset(('n', 'no', 'off', '0', 'false', 'f', 0, 0.0, False))
15:53:25 <bcoca> ^ we even do this in powershell
15:56:14 <samccann> so based on the recent comments in that community-topic - do we have a decision/consensus then that docs should use true/false instead of yes/no?
15:58:41 <felixfontein> no, but I think we should start a vote on this in community-topics. once that is concluded, we will have one :)
15:59:01 <felixfontein> and then we can put this topic back to rest... until the next reboot ;-)
16:01:32 <samccann> heh
16:01:48 <samccann> so is that agreement we should switch to trure/false?
16:02:01 <samccann> or wait another week to see if there are more comments?
16:02:27 <bcoca> i really dc unless someone wants to change ansible-doc
16:03:42 <felixfontein> bcoca: what would be your opinion if changing ansible-doc is also on the table?
16:03:56 <bcoca> 'PR is closed'
16:04:24 <felixfontein> we can open a new one ;)
16:04:32 <samccann> heh
16:04:38 <bcoca> bot can handle as many as you can open
16:06:02 <samccann> ok we are five minutes over.. time to wrap up unless someone has something else to say?
16:08:00 <samccann> heh ok so you would block any change? or just being sarcastic?
16:11:05 <samccann> ok can't  tell if I'm hitting the bridge lag again or not. gonna end meeting and let the bots catch up
16:11:13 <samccann> #endmeeting