14:31:42 <samccann> #startmeeting DaWGs aka Docs Working Group
14:31:42 <zodbot> Meeting started Tue Oct 29 14:31:42 2019 UTC.
14:31:43 <zodbot> This meeting is logged and archived in a public location.
14:31:43 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:43 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:43 <zodbot> The meeting name has been set to 'dawgs_aka_docs_working_group'
14:31:52 <samccann> who's around town to talk the docs today?
14:32:23 <bcoca> i talk to the docs all the time ... what worries me is that they might talk back
14:32:36 <samccann> they always talk back to you bcoca !!
14:32:52 <samccann> #chair Xaroth bcoca
14:32:52 <zodbot> Current chairs: Xaroth bcoca samccann
14:33:16 <bcoca> samccann: you hear them too?
14:33:19 <acozine> I'm half here, will be fully here in half an hour
14:33:28 <samccann> do we have gundalow as furniture today as well?  felixfontein ?
14:33:37 <samccann> #chair acozine
14:33:37 <zodbot> Current chairs: Xaroth acozine bcoca samccann
14:33:45 <bcoca> i have 2 other meetings soon
14:33:57 <samccann> you can be a reclyner for the first half of the meeting acozine
14:34:14 * samccann fires up clone machine for bcoca... again...
14:34:14 * acozine leans waaaay back
14:34:53 <samccann> ok first thing on the agenda...
14:35:13 <samccann> #topic Fixing edit Github on CLI autogenerated pages
14:35:17 <samccann> #link https://github.com/ansible/ansible/pull/63697
14:36:40 <samccann> Anyone have thoughts on the proposed fix? gits into some coding I'm not familiar with so wanted opinions etc
14:38:01 <bcoca> not sure i understand what they are doing nor if it is correct
14:39:38 <gundalow> samccann: I'll take a chair
14:39:39 <bcoca> also looks like adding or .. endswith(*'-cli') achives teh same with less code duplication
14:39:52 <bcoca> #bench gundalow
14:39:54 <samccann> well the general problem is edit on github links  are not working I guess on CLI pages
14:39:58 <samccann> haha
14:40:02 <samccann> #chair gundalow
14:40:02 <zodbot> Current chairs: Xaroth acozine bcoca gundalow samccann
14:40:05 <gundalow> Thanks
14:40:15 <bcoca> the github links dont wokr on any of the generated pages
14:40:35 <gundalow> 63697 so what exactly is broken today?
14:40:36 <samccann> I can bring the branch down locally and test that it works. Just need someone with a bigger cluestick to evaluate the actual code
14:40:45 <bcoca> modules are the bulk of those, but cli/conf/plugins/keywords/etc lots of others
14:41:16 <samccann> yeah I think module works but the others don't.  This one proposes to fix the cli stuffs
14:41:42 <bcoca> it just looks like a link to open a pr
14:41:58 <acozine> gundalow: if you click on "edit on GitHub" you get a 404
14:42:12 <gundalow> will need to add redirects, ie `ansible.html` -> ansible-cli.html
14:42:28 <samccann> yah. whereas if you do that for module pages, you get to edit on github for that page (which will open a PR )
14:43:10 <gundalow> ah so https://docs.ansible.com/ansible/devel/cli/ansible.html has a broken link
14:43:40 <samccann> yeah they all do in that cli category
14:43:54 <gundalow> Is it just `/cli/` pages that are broken?
14:44:00 <samccann> so the PR fixes that (partly by adding -cli to the filename) then detecting that in the fix
14:44:22 <samccann> no, as bcoca said, I think all the autogenerated pages other than modules are broken/never worked with the edit on Github button
14:44:25 <acozine> anything where the rst page title doesn't match the source code page name is "broken"
14:44:31 <gundalow> How come cli is a special case, why aren't othes broken
14:44:32 <gundalow> oh, right
14:44:51 <acozine> that link tries to point to `https://github.com/ansible/ansible/edit/devel/docs/docsite/rst/cli/ansible.rst`
14:44:59 <bcoca> pretty sure they are all broken, we've had reports about that for 5 yrs .. mostly ignored as low priority for core .. but now docs team ...
14:45:18 <bcoca> so 'modules' link points to module file
14:45:35 <bcoca> which i think is fine, but cli link would point to cli file? that woudl require editing argparse code
14:45:38 <bcoca> not so 'fine'
14:45:44 <falcon78921> hey everyone :) i opened pr #63697. if there's anything that can be improved or needs fixed, please let me know.
14:45:46 <bcoca> i think we need a 'no edit link' category
14:46:03 <samccann> welcome falcon78921 !!
14:46:10 <samccann> #chair falcon78921
14:46:10 <zodbot> Current chairs: Xaroth acozine bcoca falcon78921 gundalow samccann
14:46:19 <gundalow> +1 to `no edit link`, people can just grep the codebase for where that string is defined to find what to fix
14:46:43 <bcoca> modules is mosztly fine cause its 'yaml docs' they edit
14:46:49 <samccann> so in order to do that, would we still need to rename those pages as -cli to detect them?
14:46:58 <bcoca> though i would argue they can break sync with argspec .. but Ci catches that
14:47:17 <bcoca> samccann: no, i would match ansible*.rst
14:47:18 <samccann> I feel module edits are worth having
14:47:26 <bcoca> ^ agreed
14:47:38 <bcoca> also plugins
14:47:42 <bcoca> same issue as modules
14:47:54 <bcoca> and those are matchin plugins/*/*.rst
14:47:58 <samccann> hmm... we'd have to check that ansibl*.rst isn't  picking up any regular rst pages
14:48:21 <acozine> the module docs point correctly to the module python pages
14:48:34 <bcoca> samccann: i checked, i see no ansible*rst 'pre generating cli files'
14:48:41 <acozine> I just confirmed by trying the "Edit on GitHub" link from https://docs.ansible.com/ansible/devel/modules/user_module.html
14:48:44 <samccann> not sure I'm following bcoca - do we want to allow edits on plugins?
14:49:10 <bcoca> acozine: the template has specific case for modules altering path, this change introduces same for cli tools, which i think we shouldnt since it is 'pure code'
14:49:39 <bcoca> samccann: yes, for same reason as modules , they are embeded 'docs' ... though there they affect teh argspec since plugins use them for both
14:49:39 <samccann> #agreed - we don't want edits on the cli pages as it's not  just changing yaml etc. So remove edit on github from those cli pages
14:49:53 <acozine> falcon78921: were there things on a CLI page you wanted to update, or were you simply frustrated by the 404?
14:50:06 <acozine> what motivated you to create the PR?
14:50:18 <samccann> #info  we should allow edits on plugins as they are also embedded docs like module pages
14:50:19 <bcoca> i think we have 3 categoreis, 'no edit' : pure code, 'base edit' : direct rst pages, 'redirected edit': generated rst pages that have the docs in varios diff path sources
14:50:30 <bcoca> the last one is plugins/keywords and other stuff
14:50:37 <bcoca> and modules (but those are already working)
14:51:03 <samccann> #info also get edit on github working for other embedded docs such as keywords
14:51:04 <acozine> bcoca: what is the source for the ansible cli doc?
14:51:27 <falcon78921> well, originally i was confused on how ansible generated documentation, seeing as there wasn't a cli directory that contained .rst files
14:51:32 <bcoca> acozine: a bit complicated, its mixed, there is general location and aggregated per cli
14:51:43 <falcon78921> i finally realized that the docs were generated from the code
14:51:54 <acozine> falcon78921: yeah, that takes a bit of tracking down
14:52:03 <bcoca> https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/adhoc.py#L49
14:52:11 <bcoca> ^ that is for 'ansible' which is not straightforward
14:52:19 <bcoca> as ansible = adhoc internally
14:52:27 <bcoca> while the rest of ansible-X = X internally
14:52:38 <bcoca> so ansible-doc = cli/doc.py
14:52:49 <bcoca> but most of the options are in 'helpers' files
14:53:00 <bcoca> or in the base __init__.py class
14:53:03 <acozine> so there really isn't anything to edit there, right? the docs are directly generated, it's not an embedded docstring like the module docs
14:53:11 <bcoca> so only PART of the options are updatable in each file
14:53:31 <bcoca> from line 49 you get -a/--args
14:53:34 <falcon78921> my thought was making sure the edit on github link worked
14:53:36 <bcoca> 'module arguments'
14:53:42 <falcon78921> in order to get more participation
14:53:44 <bcoca> for cli, it wont work
14:53:55 <falcon78921> but it looks like i still don't clearly understand how some of the docs are generated
14:53:55 <bcoca> but for plugins and keywords faq, we can make it work easily
14:54:09 <acozine> falcon78921: that's a great idea, and thank you for all the work you put in
14:54:12 <gundalow> falcon78921: Nice work on working your way though this and fighting through it till you got a PR that improves the situation :)
14:54:18 <bcoca> falcon78921: depends on which set of docs, the 'cli' ones are generated from the argsparser data, same as man pages
14:54:43 <bcoca> TIL that we had made module edit pagges work ...
14:54:48 <bcoca> those didnt for a long time
14:54:59 <acozine> that was a while ago, and it really has generated more participation
14:55:04 <bcoca> ^ but see my 3 categories above
14:55:10 <acozine> we get a ton of typo fixes and other stuff on the module docs
14:55:40 <acozine> but I agree that the CLI docs are different
14:55:42 <bcoca> i'm all for makign the links work in more cases, but cli i think should be an exceptoin, it requires actual code changes
14:55:55 <acozine> agreed
14:55:57 <falcon78921> bcoca: i understand
14:56:26 <bcoca> https://github.com/ansible/ansible/blob/devel/docs/docsite/keyword_desc.yml <= source for keyword faq
14:56:29 <falcon78921> thank you everyone for the feedback :)
14:56:37 <bcoca> and plugins would work very much like modules
14:56:41 <acozine> so now the question is, how do we suppress those links in the published docs?
14:56:53 <acozine> because we do not want to leave broken links out there if we can help it
14:56:55 <bcoca> that is easy part, the if had 'nothing' inside
14:57:14 <bcoca> dont create link for those cases, explicitly, right now the default is to create a link
14:57:31 <bcoca> the same 'if' falcon78921 has genrated could be used to suppress teh github edit link
14:57:45 <acozine> even better . . .
14:58:00 <acozine> falcon78921: would you be willing to modify your PR to do that?
14:58:16 <samccann> does it require changing the filename to -cli and redirects?
14:58:28 <falcon78921> yeah, so you just want breadcrumbs.html modified right?
14:58:35 <falcon78921> revert the other cli changes
14:58:46 <acozine> samccann: it shouldn't, no
14:58:55 <samccann> kewl
14:59:06 <bcoca> no, the 'ansible*.rst' matching shoudl work
14:59:27 <bcoca> i originally wanted a /cli/ dir but someone else wrote the final part and put them on tld
15:00:02 <bcoca> i was happy it was done (i had no time) but sad it didnt use /cli/ to make it easy to exclude/include for stuff like this
15:00:25 <bcoca> so i made sure no other files on / used ansible*rst pattern
15:01:01 <acozine> bcoca: the docs are in a /cli/ dir: https://docs.ansible.com/ansible/devel/cli/ansible.html
15:01:13 <acozine> so is the code: https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/adhoc.py#L49
15:01:17 <bcoca> docs/docsite/rst/cli/ansible-*.rst
15:01:19 <bcoca> docs/docsite/rst/cli/ansible.rst
15:01:21 <bcoca> ^ in gitignore
15:01:31 <samccann> can't remember if I did this already or not so...
15:01:40 <bcoca> ah, so they were moved?
15:01:44 <samccann> #agreed remove edit on Github links for cli pages
15:01:51 * bcoca wonders if he did that and then forgot
15:02:06 <bcoca> `'/cli/' in `
15:02:27 <samccann> since we are talking about this Edit on Github, can we morph into how to fix this for plugin pages?
15:02:48 <bcoca> its easy enough, very close to how modules do it
15:03:27 <samccann> dare I ask... falcon78921  - does this sound like something you might be interested in tackling after the cli pages in a separate PR?
15:03:47 <samccann> no/don'thavetime etc are fine answers :-)
15:04:09 <bcoca> on related note, that i keep forgetting to add to agenda, we could create link to keywords faq from pages using a keyword?
15:04:20 <samccann> just figure if you are in there and looking for something to try your hand at next... would be a great help (both of these are, as you might have guessed by how long the issues been around)
15:04:21 <bcoca> i think a lot of people see kewyrods just in examples and never read the description
15:04:29 <falcon78921> samccann: yeah, i can try :)
15:04:35 <samccann> woot thanks!!
15:04:37 <bcoca> falcon78921++
15:05:21 <acozine> bcoca: example of a page using a keyword? are you talking about the module docs?
15:06:02 <samccann> the playbook keywords page is what you want folks to link to?
15:06:46 <acozine> so this would be the target page: https://docs.ansible.com/ansible/devel/reference_appendices/playbooks_keywords.html
15:06:53 <bcoca> yep, too many people keep seein 'environment' used in a play example, but no explanation/descript ion of what keyword actually does .. then they infer a lot of not true things
15:07:07 <samccann> #topic linking to Playbook keywords from other examples
15:07:20 <acozine> bcoca: examples in the module docs? or elsewhere in the docs?
15:07:29 <bcoca> all over
15:07:37 <acozine> module docs would be tough, I think
15:07:40 <bcoca> apt moduel is one case i know off top of head
15:07:47 <samccann> #link https://docs.ansible.com/ansible/devel/reference_appendices/playbooks_keywords.html
15:07:51 <bcoca> https://docs.ansible.com/ansible/latest/user_guide/playbooks_environment.html <= also update this since it doesn't clarify the definition
15:08:12 <acozine> sp / / / https://docs.ansible.com/ansible/devel/modules/apt_module.html#examples
15:08:53 <acozine> bcoca: that page is under review right now, I'll incorporate your comment, thanks!
15:09:06 <bcoca> https://github.com/ansible/ansible/issues/63947 <= we get this kind of issue all the time
15:09:53 <acozine> that's an excellent example to work from, thanks
15:10:15 <samccann> #link https://github.com/ansible/ansible/issues/63947
15:10:37 <samccann> #info use issue 63947 for an example of the confusion the environment keyword causes users
15:10:51 <samccann> #link https://docs.ansible.com/ansible/latest/user_guide/playbooks_environment.html
15:11:15 <samccann> #info playbooks_environment.rst also needs updating as it doesn't clarify the definition
15:12:26 <samccann> ok anything else on this topic before we move it PRs?
15:13:15 <samccann> ok
15:13:21 <samccann> #topic Docs PRs
15:14:06 <samccann> This one is a good starter - https://github.com/ansible/ansible/pull/64041
15:15:34 <acozine> ah, so this changes the example to cover invalid variable names?
15:15:51 <acozine> interesting
15:16:00 <acozine> I can see both sides to this
15:16:19 <samccann> to be honest, I'm not sure what it's doing
15:16:55 <samccann> I thought it was just trying to correct the jinja2 example of how to pull out the interface/ip addr from an ansible fact result?
15:17:18 <acozine> I think it's a way of getting around variable names with dashes
15:17:25 <acozine> https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#creating-valid-variable-names
15:17:32 <acozine> ^^^ covers what's a valid variable name
15:17:55 <acozine> and `-` is not allowed, but `_` is allowed
15:18:13 <acozine> so the transformation there replaces `-` with `_`
15:19:35 <acozine> bcoca: gundalow am I reading that correctly?
15:20:01 <samccann> this is the issue driving it - https://github.com/ansible/ansible/issues/64043
15:21:01 <samccann> ok reading that, it sounds like network interface names can use dashes (and that's not under ansible's control). So the fix is to scan for a dash and replace with underscore
15:21:31 <acozine> yeah, you can have interfaces named `tap2f186e31-b8`
15:21:42 <acozine> but that would not be a valid Ansible variable
15:22:07 <samccann> but it is a valid interface name in network land (aka outside of ansible)
15:22:14 <acozine> right
15:23:16 <acozine> I'd like to see a sentence below saying "the transformation is necessary because `-` is allowed in interface names but not in Ansible variables" and a link to the valid-variables content
15:23:39 <samccann> okay maybe add that as a comment and we can move to the next PR
15:24:04 <samccann> https://github.com/ansible/ansible/pull/64040
15:24:15 <samccann> adds a note for people using ansible in a VM
15:24:22 <acozine> samccann: I'll update the PR after the meeting is done
15:25:29 <acozine> what do you think about the VM one? Useful?
15:25:43 <samccann> I've used ansible in a VM and haven't set that parameter
15:25:58 <samccann> but this is specifically in the networking getting started.
15:26:27 <samccann> (oh and it's not a VM, its venv... my mistake)
15:27:10 <acozine> the change is to a network-specific page
15:27:29 <samccann> yeah. so I can't tell if it's an accurate fix or not really
15:28:49 <samccann> I guess I'm not understanding why it's specific to networking
15:29:07 <samccann> cuz even the page it points to in the F5 docs is I think talking about ansible on the controller
15:29:22 <samccann> but I'll ask the network folks to look
15:29:23 <samccann> meanwhile
15:29:27 <samccann> #topic OpenFloor
15:29:41 <samccann> anyone have anything they've been waiting to say? other topics?
15:30:50 <acozine> quiet, isn't it?
15:31:11 <samccann> <crickets>
15:31:17 <acozine> everyone is welcome to add issues, PRs, ideas, concerns, etc. as agenda topics
15:31:25 <bcoca> acozine: network interfaces get rewritten internally to not use - though origianls can (if linux, other archs might differ)
15:31:28 <samccann> maybe we should start the meeting with - did anyone come with a specific topic in mind?
15:31:58 <acozine> samccann: sounds good
15:32:12 <samccann> ok we are about out of time... anhyone have any last parting thoughts before we close?
15:32:28 <acozine> anyone can add an agenda item for next week using https://github.com/ansible/community/issues/389
15:32:35 <acozine> add a comment at the bottom of ^^^
15:32:45 <samccann> ok going once....
15:33:06 <samccann> twice....
15:33:07 <falcon78921> thanks again for the feedback on pr #63697 everyone! :)
15:33:22 <samccann> thanks for taking that on falcon78921 !!
15:33:36 <samccann> ok
15:33:41 <samccann> #endmeeting