15:00:58 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:58 <zodbot> Meeting started Tue Aug 16 15:00:58 2022 UTC.
15:00:58 <zodbot> This meeting is logged and archived in a public location.
15:00:58 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:58 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:58 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:14 <DonNaro[m]> aloha
15:01:14 <samccann> #topic opening chatter
15:01:20 <DonNaro[m]> o/
15:01:23 <samccann> #chair Don Naro
15:01:23 <zodbot> Current chairs: Don Naro samccann
15:01:31 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:39 <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:01:43 <DonNaro[m]> unfortunately I'm once again double booked so only partially here
15:01:45 <felixfontein> o/
15:01:50 <felixfontein> though I'm only partially around
15:02:04 <samccann> ping briantist felixfontein
15:02:17 <amott[m]> I'm here. I can listen about the docs... :)
15:02:19 <samccann> the fun you have Don Naro !
15:02:28 <samccann> #chair amott
15:02:28 <zodbot> Current chairs: Don Naro amott samccann
15:02:30 <DonNaro[m]> it's always a good time
15:02:30 <samccann> Welcome!
15:02:45 <DonNaro[m]> Welcome amott
15:02:48 <samccann> #chair felixfontein
15:02:48 <zodbot> Current chairs: Don Naro amott felixfontein samccann
15:02:59 <zbr> I am here too
15:03:04 <DonNaro[m]> hello Sorin!
15:03:05 <samccann> #chair ssbarnea
15:03:05 <zodbot> Current chairs: Don Naro amott felixfontein samccann ssbarnea
15:03:11 <samccann> full house today!
15:03:25 <DonNaro[m]> woot
15:03:32 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1209665268
15:03:37 <briantist> sorry I'm traveling and will probably miss all or most meetings this week
15:04:00 <samccann> ok thanks for letting us know briantist ! Enjoy your travels
15:05:11 <samccann> #topic Booleans
15:05:26 <samccann> :-) Since I figure that's why ssbarnea is here today!
15:05:59 <DonNaro[m]> is that why you're here ssbarnea ? true or false?
15:06:10 <samccann> heh!!
15:06:26 <samccann> #info antsibull-docs fix for true/false booleans has been merged - https://github.com/ansible-community/antsibull-docs/pull/19
15:07:37 <zbr> Also just opened https://github.com/ansible/ansible/pull/78557
15:07:57 <samccann> Trying to remember - I think the devel docs build with the most recent antsibull-docs but there isn't a release yet that includes it, so we won't see this for a little bit in devel
15:07:59 <acozine> o/
15:07:59 <zbr> that should change ansible-doc output, but i need to see which tests get broken by this
15:08:42 <samccann> #chair acozine
15:08:42 <zodbot> Current chairs: Don Naro acozine amott felixfontein samccann ssbarnea
15:09:09 <samccann> #info https://github.com/ansible/ansible/pull/78557 changes ansible-doc output as well for true/false
15:09:19 <samccann> cool thanks ssbarnea !
15:10:15 <samccann> once these two are part of devel docs builds, we can get an indication of how many files we'll have to manually change. But we do have to be careful on those as we need to be clear Ansible itself doesn't care.
15:10:54 <samccann> So ^^ that's a good discussion point.  We obviously need to say clearly that ansible-core accepts, true/false, True/false, yes, no... and whatever else.
15:11:22 <samccann> But then, do we want to go through and change anything else to stick to true/false? or just leave them as the random items they probably are today?
15:11:53 <acozine> by "anything else" do you mean examples? or are there other things?
15:12:14 <samccann> yeah examples, we may talk about it the body of the documents, I haven't actually looked.
15:13:00 <samccann> what I want to avoid is the typical PR arguments we've gotten into in the past where changes like  these were blocked.
15:13:32 <samccann> I mean now we have a community decision for true/false, but I want to see/understand if we feel that decision affects all docs, not just boolean parameters in modules/plugins etc
15:14:45 <acozine> I'd suggest adding a section to https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#playbooks-variables for "using Boolean variables" or something similar
15:15:30 <acozine> where it would clearly state "Ansible accepts a wide range of values for defining boolean variables. The documentation uses `true` and `false` for consistency and clarity
15:15:33 <acozine> * and clarity"
15:15:36 <acozine> or something along those lines
15:15:59 <samccann> acozine: can you open an issue when you get a chance pls for that? it's a good idea
15:16:25 <samccann> and could be an easyfix yea
15:16:25 <acozine> it woudl certainly be nice to update all hte examples to match, but it also seems like a low priority and something to mark `easyfix`
15:16:26 <acozine> samccann: yep, will do
15:16:55 <samccann> meanwhile the vote description was quite clear - https://github.com/ansible-community/community-topics/discussions/120
15:17:42 <samccann> So I think yes we  can accept community PRs that start that cleanup work. We could even make it part of hacktoberfest. ariordan had a lot of success running that last year and got a lot of PRs merged
15:19:41 <samccann> anything else on this topic?
15:21:54 <samccann> #topic Documentation Updates
15:22:09 <samccann> #info Starting a new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
15:23:41 <samccann> #info This is specific to docs in the ansible/ansible repository and triages incoming issues into those categories. Feedback welcome on the design and if you disagree with any of the priority settings etc
15:24:10 <felixfontein> zbr: https://github.com/ansible/ansible/pull/78557 is a breaking change, I don't think that has any chance of being merged
15:24:12 <samccann> I'm about 1/2 way through adding existing docs issues to that board and triaging them into the appropriate categories etc
15:24:54 <felixfontein> it has the potential of breaking every module and plugin there is
15:24:58 <samccann> felixfontein: can you elaborate on what it breaks (besides CI at the moment ;-)  just so's I can understand it a bit better
15:25:36 <samccann> because of how it's coded, or in general, changing ansible-doc output to true/false is that dramatic?
15:25:37 <felixfontein> it basically changes a utility function that is used by almost everything (every plugin and every module)
15:26:13 <bcoca> we jsut saw that, totally wrong place for that change, also please dont force formatting on ansible-doc yaml/json output
15:26:26 <samccann> so is there some other place where we can just massage the output?
15:26:43 <bcoca> anstibull
15:26:50 <samccann> i mean ansible-doc output
15:26:53 <felixfontein> bcoca: that's HTML only
15:26:55 <samccann> antsibull-docs is done
15:27:01 <bcoca> k, then we are done
15:27:04 <felixfontein> (well, and RST)
15:27:12 <samccann> so we need/want to be consistent
15:27:16 <bcoca> well, it is rst and then html
15:27:25 <bcoca> samccann:  we are, with our pyyaml lib output
15:27:29 <samccann> so if I search foo module and see boolean is true false there, but display that same module on ansible-doc and it says yes/no, we have problems
15:27:38 <bcoca> i dont want to add constructors for booleans
15:27:59 <bcoca> it displays 'true' 'false' already when using --json output
15:28:10 <felixfontein> add a new wrapper function in doc.py that preprocesses booleans before passing them to to_text in https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/doc.py#L1098 (and probably some more places)
15:28:22 <bcoca> please don't
15:28:24 <acozine> Issue opened: https://github.com/ansible/ansible/issues/78559
15:28:41 <samccann> ok for the unwashed masses (aka me) - will foo module display different things between html and ansible-doc output bcoca
15:28:52 <felixfontein> bcoca: I'm just pointing out the probably best way to do that change just for ansible-doc (and not random other stuff)
15:28:56 <samccann> acozine: cool thanks!
15:29:00 <bcoca> it will display diff things on diff options in ansible-doc alone
15:29:24 <bcoca> felixfontein: and im saying dont do the change for ansible-doc
15:29:45 <felixfontein> I don't see why 'True' and 'False' should be used for booleans in ansible-doc text output. the only argument I can see is "it has always been like that"
15:30:19 <bcoca> i just want to keep it out of mangling the formats ... we do too much already with the text strings  and that creates a slew of maintenance issues
15:30:40 <bcoca> and since im revamping the system as we speak, less changes are desired
15:31:15 <samccann> @bcoca - does that mean AFTER you revamp, we can get true/false for ansible-doc output?
15:31:19 <samccann> aka now is a bad time, but later would work?
15:31:25 <felixfontein> I hope this isn't yet another "ok we do the changes when you're done ... oh, that PR got merged just before feature freeze, no more chance to change anything :("
15:31:32 <bcoca> ij would still be against it, since that is format dependant
15:32:05 <samccann> format dependent means what? Sorry not following that part.
15:32:24 <felixfontein> I think he means that text format output should be (treated) different from JSON format output
15:32:40 <felixfontein> I still don't see why the text output should use 'True' and 'False', out of all possibilities
15:32:49 <felixfontein> (but that's another topic)
15:32:52 <bcoca> it uses what pyyaml outputs
15:32:54 <samccann> yeah ^^ is what I don't get either
15:32:58 <felixfontein> bcoca: it does not.
15:32:58 <bcoca> and i dont want to change that
15:33:10 <felixfontein> bcoca: it does what Python str() outputs
15:33:16 <samccann> ah okay so ansible-doc uses pyyaml output, unless you say --json
15:33:16 <bcoca> then where at they comming from?since even true/false and 0/1 get converted
15:33:42 <samccann> From an end-user perspective, we want consistency
15:33:52 <felixfontein> pyyaml converts the booleans to Python booleans, and ansible-doc uses str() (in disguise of to_text()) to convert them to 'True' and 'False' strings
15:33:56 <bcoca> felixfontein: no, booleans should be processed from pyyaml not as strings (though we do stringfy the output, but pyyaml has already done this)
15:34:07 <samccann> So documentation (html), ansible-doc, and AH/GalaxyNG should say the same things
15:34:14 <bcoca> felixfontein: no, pyyaml conversts FROM PYTHON in this case
15:34:24 <bcoca> even though it also converted TO python initially
15:34:29 <bcoca> it handles BOTH
15:34:42 <bcoca> samccann: no, they arenot the same formats
15:34:51 <felixfontein> bcoca: https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/doc.py#L1098 is the line whcih converts proper booleans to 'True' and 'False' strings
15:34:54 <bcoca> if tomrrow you decide on yes/no, we would have same issue
15:35:01 <felixfontein> (at least for 'default:')
15:35:51 <bcoca> felixfontein: and that is the result from previous yaml_dump
15:36:00 <samccann> @bcoca how are they not the same from the end-user perspective? I read docs, or I read AH, or I read the output of ansible-docs
15:36:14 <felixfontein> bcoca: it is not
15:36:17 <bcoca> which makes it already text, not a boolean (was python boolean) but all  yaml_dump output is text
15:36:49 <bcoca> samccann: diff formats are handled diferently, or do you see the --json outputing 'yes' np'?
15:36:53 <felixfontein> pyyaml converts Python booleans to 'true' and 'false' already
15:37:13 <bcoca> felixfontein: then that should be what is displayed
15:37:19 <samccann> --json is a specific user decision. if boolean means something different in --json, that's fine.
15:37:26 <felixfontein> bcoca: yes, but ansible-doc does something else so that the result is different
15:37:43 <bcoca> --yaml --toml (and hoepfully never --ini)  are the others, with yaml being default
15:38:05 <felixfontein> bcoca: that's not true for the current `devel` version and the current released version
15:38:09 <bcoca> felixfontein: show me where, cause removing a transformation im ok with, forcing new ones i am not
15:38:15 <felixfontein> (it might be true for your PR, but that's not what we currently have in `devel`)
15:38:31 <felixfontein> bcoca: I showed you the place multiple times
15:38:48 <felixfontein> https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/doc.py#L1098
15:38:54 <bcoca> that does indentation, not change true to True
15:39:13 <felixfontein> that does change true to True
15:39:14 <zbr> I don not know why we discuss about JSON output, there is no change needed on that area.
15:39:17 <felixfontein> set a breakpoint and check it out
15:39:20 <bcoca> at most yhou could say our use of 'null' to be a transformation
15:39:26 <cidrblock[m]> o/
15:39:41 <samccann> #chair cidrblock
15:39:41 <zodbot> Current chairs: Don Naro acozine amott cidrblock felixfontein samccann ssbarnea
15:39:45 <samccann> Welcome!
15:39:47 <cidrblock[m]> TY :)
15:39:57 <felixfontein> it also converts None to 'None' (and not 'null' or `~` or whatever pyyaml would use)
15:40:00 <bcoca> to_text does not capitalize
15:40:20 <felixfontein> bcoca: it does, since the input is a Python boolean, and not a string
15:40:45 <felixfontein> add a `print(type(opt.get('default')))` in the previous line and run it
15:41:18 <bcoca> sigh, cause we dont pass  default to yaml_dump direclty  .. k, i was  talking booleans in general, for derfault we do that so 'None' is not used (since it cannot be) , so this is python stringification
15:41:31 <bcoca> but rest of booleans should be going through yaml_dump
15:41:40 <bcoca> default was special cased cause of None
15:42:26 <felixfontein> both `default` and `choices` are using Python stringification, and that's exactly the main places we want changed
15:42:36 <felixfontein> the places where pyyaml is used are fine
15:42:57 <bcoca> well, choices is not supposed to be booleans .. though it can be, type: boolean does not require choices
15:43:03 <bcoca> its for type list and similar
15:43:36 <bcoca> converting all those to yaml_dumps is acceptable, less text processing
15:43:44 <bcoca> but willc reate unicode issues
15:43:50 <bcoca> which is why that is being done
15:44:38 <felixfontein> I'm fine with using to_text, except for booleans
15:44:53 <bcoca> in choices you dont know what is supposed to be a boolean
15:44:59 <felixfontein> that's why my suggestion is to add a wrapper function that treats booleans differently, and uses to_text for everything else
15:45:03 <bcoca> and even booleans end up as text and we use to text in the end
15:45:26 <bcoca> we might be able to just ignore it in many places, but not when doing concatenation and the like
15:45:41 <bcoca> a way around that is forcing yaml_shorthand, let yaml deal with the concat
15:45:49 <bcoca> same with default
15:46:16 <bcoca> we should not be doing null stransformation (see why im against text transfomrations?)  it creates more issues  than it solves
15:47:06 <felixfontein> I don't care that much how exactly it works, as long as the output is 'true'/'false' for booleans and not 'True'/'False'
15:47:29 <bcoca> https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/doc.py#L1144 <= if we remove the excceptions, this should do all the work
15:47:50 <bcoca> felixfontein: i dont care about the exact output, i care about adding more transformations
15:48:21 <acozine> can we keep the current number of transformation and end up with the desired output?
15:48:31 <bcoca> not really
15:48:37 <acozine> s/transformation/transformations/
15:48:47 <bcoca> since the transformations are the ones creating the output you want to change
15:50:39 <acozine> we have one transformation that currently generates `True` and `False` - can't we modify it to generate `true` and `false` instead?
15:51:00 <bcoca> its not just one
15:52:10 <bcoca> there are 3 and then recursive calls from suboptions that would hit those 3 again
15:53:51 <bcoca> in 142  change to to_text(yaml_dump({entry: default}, default_flow_style=False), errors='surrogate_or_strict')) <= for 'is sequence (which would include choices) and remove all the processing above them for choices/defaults/issqeuence
15:54:55 <bcoca> to keep backwards compat you might want to do 'default is none then '(none)' + pop, otherwise just let it through to the 144 line
15:55:10 <bcoca> requied is the one i want to remove but cannot ...
15:57:35 <samccann> we only have a few minutes left. Have we discovered a technical solution here?
15:57:54 <acozine> I'd need a description in English of what the code is doing to really understand this - something like "we take the values in the python docstrings and we convert them to format X (code snippet illustration here), then we take that output and check it for problem Y (code snippet again). Once that's done we change format X into a string (code snippet)" and so on
15:58:11 <bcoca> acozine: we need to remove teh currenet 'python stringification' and let yaml do it
15:58:28 <samccann> and that fixes it to true/false?
15:58:29 <bcoca> that is something im fine with, what i don't want is more 'text conversions'
15:58:51 <bcoca> samccann: it makes it output whatever pyyaml defaults to, which  felixfontein confirmed is what you want
15:58:54 <samccann> #info the ansible/ansible 'fix' is to remove the current python stringification and let yaml do it
15:59:25 <samccann> ssbarnea: do you follow ^^ above, and if so, can you create another PR (or edit your existing one) to do  this?
15:59:28 <bcoca> note that it leaves the control on the pyyaml side and  if tomorrow they swhitch to 0/1  .....
15:59:43 <acozine> yikes, i need to run to $nextmeeting
15:59:50 <acozine> thanks everybody!
15:59:57 * samccann plays the lottery and hopes to hit BIG before pyyaml changes
15:59:58 <acozine> #unchair acozine
15:59:58 <zodbot> Current chairs: Don Naro amott cidrblock felixfontein samccann ssbarnea
16:00:12 <samccann> thanks acozine !
16:00:28 <samccann> ok a quick...
16:00:29 <samccann> #topic Open Floor
16:00:44 <samccann> in case anyone has hung around this long - here's your chance to bring up anything docs related today!
16:02:44 <samccann> ok seems like that's about it for today
16:02:46 <samccann> #endmeeting