15:31:10 <acozine> #startmeeting Documentation Working Group aka DaWGs
15:31:10 <zodbot> Meeting started Tue Mar 26 15:31:10 2019 UTC.
15:31:10 <zodbot> This meeting is logged and archived in a public location.
15:31:10 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:31:10 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:31:10 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:31:15 <acozine> who's around?
15:32:37 <acozine> helloooooo? anybody here?
15:32:45 <samccann> ooph sorry! here!
15:32:53 <acozine> #chairs samccann
15:33:08 <acozine> #chair samccann
15:33:08 <zodbot> Current chairs: acozine samccann
15:33:14 <acozine> I get that wrong every time
15:33:25 <samccann> consistency is important ;-)
15:33:28 <acozine> heh
15:34:17 <acozine> anybody else? felixfontein gundalow dag decentral1se Xaroth Pilou you folks ready to talk docs?
15:34:30 <samccann> talk the docs!
15:34:37 <acozine> we've got an easy one to start with:
15:34:39 * gundalow waves
15:34:41 <acozine> https://github.com/ansible/ansible/pull/54288/files
15:34:45 <acozine> #chair gundalow
15:34:45 <zodbot> Current chairs: acozine gundalow samccann
15:34:47 <Xaroth> Suffering from ebola or whatever monstrosity I have caught, so I'll probably not be useful.
15:35:11 * acozine is glad we're only breathing the same digital air
15:35:45 <acozine> Xaroth: I won't make you a chair, then . . . hope you can get some down-time and heal
15:36:03 <Xaroth> <3 Thanks, and I hope so too.
15:36:11 <samccann> how about a comfy cushion?
15:36:28 * samccann feels punny today
15:36:39 * acozine groans
15:36:51 <Xaroth> That took me way too long to notice.
15:36:52 * acozine and refuses to make Xaroth a comfy cushion
15:37:03 <gundalow> 54288 has +1 from maintainer, and from someone else so mergeit
15:37:31 <samccann> i got myself all twisted up about that one yesterday
15:37:34 <acozine> only concern on it was that apparently ports 60K - 61K are commonly used by some unsavory types
15:38:03 <samccann> that port range if you google it, comes up as common ports for maleware... so I wondered if we should request either a port range change, or rule change to deny?
15:38:39 <gundalow> Well people will only enable it if they have a legitimate reason. Firewall defaults are generally "block everything then allow specific"
15:38:46 <gundalow> so I' think it's good to merge
15:38:53 <acozine> I hope people aren't picking actual port numbers from our examples
15:38:56 <acozine> right, merging
15:39:53 <acozine> ugh, GitHub is having a rough day again
15:39:58 <acozine> well, I'll merge it when I can
15:40:04 <gundalow> acozine: yup, GitHub is being slow :(
15:40:19 <acozine> okay, so our next topic is . . .
15:40:37 <acozine> #topic finding the Module Dev Tips and Tricks page
15:41:02 <acozine> so the page in question is https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_best_practices.html
15:41:42 <acozine> gundalow, you're hearing that people aren't finding it, or you're guessing they aren't because they aren't following the suggestions when the submit module code?
15:42:21 <gundalow> I keep on brainfarting on it, so I guess others are
15:42:29 <acozine> it is a little obscure - it's linked from the bottom of https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_checklist.html
15:42:36 <acozine> let me check the main dev guide TOC
15:43:19 <gundalow> I wonder if we could deletemost of `Contributing to Ansible: subjective requirements` and just put
15:43:19 <gundalow> Other Checklists
15:43:20 <gundalow> * All modules -> Link to developing_modules_best_practices.html
15:43:20 <gundalow> * Amazon
15:43:20 <gundalow> * Windows
15:44:13 <samccann> we could add a link from the dev guide indext page
15:44:26 <acozine> hmmm, well, I want to keep the text that says "checking all the boxes isn't enough" - to forestall "I checked every box, merge my code NOW" demands
15:44:43 <acozine> We could definitely add a line to this section of hte TOC:
15:45:05 <acozine> https://www.irccloud.com/pastebin/NXZFPcxr/
15:45:13 <gundalow> How about keeping the next, though changign the bullet points like I put above?
15:45:59 <acozine> Yeah, bulleted lists are good
15:46:02 <acozine> easy to read, clear
15:46:14 <gundalow> ie we'd link to it twice
15:46:26 <samccann> make sense
15:47:03 <acozine> what does the auto-response to new module PRs look like?
15:47:40 <acozine> could we include a link to that page on the PR, a sort of "if you haven't seen this page, take a look while your PR is awaiting review"
15:48:06 <acozine> that's catching people late in the cycle, but better late than never?
15:48:24 <acozine> this is in addition to adding the links, I'm in favor of that too
15:48:49 <gundalow> acozine: You mean from the bot? Nothing specific, though I'd like it to look something like https://gist.github.com/gundalow/29f8565b9cdd6fd2056e04a03823511b
15:49:56 <acozine> I like that - could be tightened up a bit, but a nice approach
15:50:12 <gundalow> urgh, that gist hasn't rendered at all well
15:50:25 <samccann> +1
15:50:33 <gundalow> very much WIP ideas at the moment, feel free to ping stuff on there
15:50:36 <samccann> really like that addition
15:51:56 <acozine> very cool
15:52:57 <gundalow> #agreed add developing_modules_best_practices.html to bullet point list and `s/Other Checklists/Checklists`
15:52:58 <gundalow> Thanks
15:53:07 <acozine> awesome
15:54:06 <acozine> anything else to discuss? we've got two long-running topics - the version-changer and the Scenario Guides consolidation PR
15:54:36 <acozine> I haven't made much progress on the Scenario Guides thing - I should have a revised version to present before next week
15:54:40 <samccann> I would like to talk about ansible-lint running against doc examples in rst
15:54:49 <acozine> #topic ansible-lint and docs examples
15:54:57 <acozine> samccann: the floor is yours!
15:55:26 <samccann> so the idea acozine and I talked about the other day was moving playbook snippets out of the rst and into a common (or set of common) directories so we could  run ansible-lint against them
15:55:44 <acozine> +1
15:55:45 <samccann> the idea being we could eventually include ansible-lint in the automated docs testing?
15:56:09 <gundalow> mattclay: FYI this (running ansible-lint (or at least yamllint) against examples in docs may be of interest to you
15:56:23 <acozine> this will set us up for using molecule too, if we include more than just snippets in the docs
15:56:38 <samccann> what does molecule do? I've lost the plot on that one
15:56:52 <acozine> Molecule tests roles, and the plan is for it to test playbooks as well
15:57:02 <acozine> so if we had full playbooks in our docs, we could test them
15:57:06 <acozine> in theory, at lest
15:57:11 <acozine> s/lest/least
15:57:17 <samccann> kewl. Yes, I think that would be a great long term goal
15:57:25 <gundalow> Starting off with yamllint (or ansible-lint) would be good
15:57:39 <acozine> much more achievable in the short term, for sure
15:57:44 <samccann> so that would add to this discussion - what can we do today with ansible-lint... and can that solution be useful longer term for molecule
15:58:12 <samccann> aka if we move all the playbook snippets into a directory so ansible-lint can run against them... will that also work in the future for molecule against real playbooks
15:58:17 <bcoca> also remember, ansible-lint's defaults are not currently what we might want
15:58:29 <bcoca> i.e playbooks are not allowed to have tasks, only roles:
15:58:38 <acozine> bcoca: oh interesting
15:58:47 <samccann> mmm... I ran ansible-lint against playbooks the other day and they came out clean
15:58:54 <bcoca> and even yamllint is opinionated on things that really are not a problem
15:59:15 <bcoca> samccann: they might have fixed that ...i had some strong words about it , so did others
15:59:22 <bcoca> but it is still a work in progress
15:59:30 <acozine> could we create a "docs standard" configuration for ansible-lint and document it so everyone knows what we use?
15:59:32 <samccann> but if we set up automated testing with ansible-lint, could we also set it up for what we want?
15:59:41 <samccann> yeah she said it better :-)
15:59:43 <bcoca> so +1 to linting, but you might want to do close review on which rules are followed
15:59:53 <gundalow> Would be interested to run yamllint/ansible-lint across a few bits of the docs to see how it looks
16:00:19 <samccann> I'm assuming we need the snippets in their own yaml files for it to work, right?
16:00:26 <bcoca> also consider, not all doc 'ansible code' is meant to be complete, a lot are single tasks or partial tasks, which are not 'valid' roles/playbooks
16:00:38 <bcoca> so be ready to create a lot of exceptions
16:00:39 <samccann> I am up for  trying this on the andvanced network guide as it only has about 10 snippets
16:00:42 <acozine> bcoca: we can lint tasks, though, right?
16:01:14 <samccann> yeah I think I did ansible-lint some tasks as well and they came clean. but I can experiement cuz most of what adv. network guide has is tiny snippets of tasks
16:01:14 <bcoca> acozine: yamllint, yes, ansible-lint, unsure .. it had soo many false positives i never started using it
16:01:35 <samccann> bcoca I think it's gotten better :-)
16:01:47 <acozine> Progress!
16:02:06 <bcoca> probably, it has a nice system to use 'custom linting rules' but no clear way to do it adhoc, which is what i would recommend for doc linting
16:02:09 <samccann> oh wait... false positive meaning it comes out clean but really isn't?
16:02:25 <bcoca> samccann: no, that is false negative
16:02:32 <samccann> oh haha ok
16:02:45 <bcoca> that it complained a lot about things that were not issues, but it also did have false negatives, just not as noticable
16:03:01 <acozine> Any thoughts on structure for this? My first thought is we try adding a `YAML snippets` directory for each main section of the docs (Dev Guide, Networking, etc.)
16:03:14 <bcoca> ansible-lint is more focused on 'style' than 'correctness'
16:03:33 <acozine> for the docs, we're interested in both style and correctness
16:03:48 <bcoca> ansible --syntax-check might be a better reflection of 'correctness' but it requires a plabook (currently)
16:04:12 <acozine> ah, so it checks for things like hosts, etc?
16:04:31 <bcoca> no, it does not check hosts, just that hosts: is correctly defined
16:04:41 <acozine> heh, that's what I meant
16:04:49 <bcoca> it basically 'compiles' the playbook and returns any parsing errors
16:04:56 <acozine> it checks that you have a `hosts` entry, which most of our snippets don't
16:05:09 <bcoca> which does not address 'dynamic' parts of playbooks, like include_X ,but we probably dont need that for docs
16:05:24 <samccann> okay so we could use ansible-lint against task snippets (assuming it works well today)  and ansible --syntax-check against playbooks in the docs? or would it be better to use molecule against full playbooks in the docs?
16:05:47 <bcoca> hmm, ansible -m include_tasks task_from_docs.yml --syntax-check localhost <= no need for playbook
16:06:00 <bcoca> ^ missing -a
16:06:37 <bcoca> samccann: i dont think its an either/or .. as much as 'incrementally add all of the above'
16:06:40 <acozine> samccann: molecule doesn't currently work against playbooks, only against roles
16:06:58 <samccann> #info ansible -m -a include_tasks task_from_docs.yml --syntax-check localhost doesn't reauire a playbook and may give a better 'correctness' result than just ansible-lint
16:07:07 <acozine> but yeah, let's try both ansible-lint and ansible --syntax-check and see what works
16:07:15 <samccann> sounds like a plan stan
16:07:28 <bcoca> also consider, that many examples use 'assumed vars' that will fail on check as they are not defined
16:07:47 <bcoca> so you probably need an 'exclude undefined errors' exception
16:08:36 <samccann> #info 12:07 PM <@bcoca> also consider, that many examples use 'assumed vars' that will fail on check as they are not defined - may need an 'exclude undefined errors' exception
16:09:18 <acozine> we will be the vanguard on making this work . . . or the canary in the coalmine, depending on how it turns out
16:10:18 <samccann> #action samccann to experiment with ansible-lint and ansible --syntax-check on adv networking guide task/playbook snippets
16:10:28 <acozine> awsome!
16:10:34 <acozine> topic #open floor
16:10:38 <acozine> grrrr
16:10:43 <acozine> #topic openfloor
16:10:55 <bcoca> #open sesame
16:11:01 <samccann> lol
16:11:30 * acozine is not an IRC native
16:11:31 <samccann> since we have a  couple of other folks here - do we want to bring up the version selection topic for a bit?
16:11:41 <acozine> sure
16:12:07 <acozine> last I remember we were going to investigate grabbing that functionality from the Sphinx theme
16:12:10 <samccann> I don't have the PR handy, but there were two issues  - one we need to fix the link so it stays on the same page
16:12:48 <samccann> two - that sphinx theme extension adds the version selection to the bottom of the left-hand navigation. How important is it to try to move that to the top?
16:13:01 <acozine> current draft PR is https://github.com/ansible/ansible/pull/53317
16:13:28 <samccann> and it would look and work something like the selection at the bottom of this readthedocs website - https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
16:13:36 <acozine> I would be okay with it floating at the bottom, as long as it's eye-catching
16:13:41 <samccann> that's how it works 'natively' if we grab that code
16:14:08 <samccann> not sure what kind of control we have on the 'eye catching' aspect since it's all new to me
16:14:28 <acozine> we could try changing the colors so the brighter color was the background
16:14:38 <acozine> that *should* be a simple CSS change
16:15:31 <samccann> worth a try
16:16:41 <samccann> gundalow: do you happen to know why we chose to copy the sphinx theme into the ansible docs source code instead of using it as a package (aka instead of pip install sphinx-rst-theme or whatever it's called)
16:16:52 <acozine> and I think the page thing should work with this logic: redirect to <other_version>/path/to/<current_page>.html; if that returns a 404, redirect to index.html
16:17:00 <samccann> basically we have a copy of that from a while ago so it's quite old
16:17:21 <samccann> #info 12:16 PM <@acozine> and I think the page thing should work with this logic: redirect to <other_version>/path/to/<current_page>.html; if that returns a 404, redirect to index.html
16:17:25 <gundalow> samccann: Not sure, before my time. Maybe so we could modify it, make so it's easier for people to build locally and get the same results
16:17:36 <samccann> ok. thanks
16:18:51 <acozine> I'd hesitate to build our theme "live" with current changes from Sphinx - we might get changes we didn't like, and not notice for a while
16:19:10 <acozine> could we set up a quarterly update schedule, maybe?
16:19:18 <gundalow> I'm not sure if we have local modifications in files that RTD ships. If they can be moved to an `overrides` directory (if such a thing exists), it may make it easier to update
16:19:25 <samccann> well it's a particular installed version. so perhaps if we don't upgrade until we've tested the latest we'd be okay?
16:19:55 <acozine> that sounds reasonable samccann
16:20:24 <acozine> we also want to check for any local changes we've made to the theme
16:20:41 <gundalow> making a note somewhere of pages to test would be good (pages with various local changes, nested option tables in module options/returns) etc
16:20:52 <acozine> good idea
16:21:06 * gundalow needs to drop off now
16:21:13 * acozine waves to gundalow
16:21:28 <acozine> thanks gundalow!
16:24:09 <acozine> #info check whether we can place local modification to the Sphinx RTD theme in a persistent `overrides` directory to preserve them when we update the theme
16:25:20 <acozine> #info develop list of pages that might be affected by RTD theme upgrades so we can check those with each upgrade
16:25:42 <acozine> hrm, those should probably be action items
16:26:08 <acozine> okay, we've got five minutes left . . . any other topics?
16:26:13 <acozine> #topic openfloor
16:27:29 <acozine> hearing none . . .
16:27:37 <acozine> thanks everybody for joining in!
16:28:07 <acozine> as a reminder,  anyone can add agenda items by adding a comment to https://github.com/ansible/community/issues/389
16:28:19 <acozine> talk to folks next week!
16:28:30 <acozine> #endmeeting