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