15:01:03 <acozine> #startmeeting Documentation Working Group aka DaWGs
15:01:03 <zodbot> Meeting started Tue Jun 18 15:01:03 2019 UTC.
15:01:03 <zodbot> This meeting is logged and archived in a public location.
15:01:03 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:03 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:03 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:09 <acozine> who's around?
15:01:13 <acozine> #chair felixfontein
15:01:13 <zodbot> Current chairs: acozine felixfontein
15:01:43 * samccann waves
15:02:10 <felixfontein> I'm partially around ;)
15:02:18 <acozine> alongchamps: andersson007_ dag mrproper orthanc Pilou shaps Xaroth66 you folks available?
15:02:24 <acozine> #chair samccann
15:02:24 <zodbot> Current chairs: acozine felixfontein samccann
15:02:57 <alongchamps> I'm not today; still catching up from being off a few days
15:02:59 <acozine> felixfontein: I saw you put things on the agenda - would you prefer we address those first? last?
15:03:10 <acozine> alongchamps: gotcha - hope the time off was fun!
15:03:17 <felixfontein> any order is fine, whatever you prefer. I probably have to leave in ~45 minutes though
15:03:55 <acozine> #topic pygments updates and lexer usage - see https://github.com/ansible/ansible/pull/57508
15:04:32 <felixfontein> background: the changes I added to the pygments lexers have been added to the official pygments release, so a lot of code can be scrapped
15:04:48 <acozine> felixfontein: thank you for creating the local lexers when we needed them, and for working to remove them now that pygments has incorporated them
15:04:48 <felixfontein> doing that turned up some places where documentation was invalid (no idea why that wasn't flagged before)
15:05:09 <acozine> the `cannot lex` errors do seem . . . unreliable
15:05:10 <felixfontein> the AnsibleOutput lexer is still there, because it's too much WIP to be submitted officially to pygments IMO :)
15:05:47 <acozine> do you think others would use the AnsibleOutput lexer if it were part of pygments?
15:06:22 <felixfontein> potentially yes
15:07:10 <felixfontein> if you want to write a blog post about ansible and want some nicely formatted ansible output, that could be usefull (assuming your blogging system supports pygments, that is)
15:07:21 <felixfontein> but that's not a project I want to invest much time in :)
15:07:23 <samccann> so does this mean I need to install pygments locally to do the doc build after this is merged? (make webdocs)??
15:07:38 <felixfontein> samccann: you already needed to do that before
15:07:53 <felixfontein> now you need a newer version, in case you had an older one
15:08:06 <acozine> after this is merged, we will only use local code for one lexer, instead of for several
15:08:38 <felixfontein> pygments 2.4.0 or newer contains all relevant YAML and Jinja2 changes
15:09:23 <samccann> can we update this page with that info - https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#before-you-open-a-complex-documentation-pr
15:09:32 <samccann> i don't see it there as a requirement?
15:09:32 <acozine> I'm happy to merge the PR, though the branch needs a (trivial) rebase
15:09:44 <acozine> samccann: I think pygments is installed as a dependency of sphinx
15:09:46 <felixfontein> oh, it actually does, I didn't notice
15:09:58 <felixfontein> I can rebase in a minute
15:09:59 <samccann> ah kewl ok
15:10:13 <acozine> felixfontein: I updated the requirements.txt yesterday when I merged our new 404 page (about which more in a while)
15:10:35 <samccann> thanks acozine  Can you look at that page tho in general?  I don't even know what tornado is but it's listed as a requirement
15:11:05 <felixfontein> samccann: adding pygments >= 2.4.0 would be a good idea
15:12:29 <acozine> samccann: oh, interesting - I have tornado installed locally, though looking at the description, I'm not sure why the docs require it: https://pypi.org/project/tornado/
15:13:25 <samccann> #action  review requirements listed here for building docs locally - https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#before-you-open-a-complex-documentation-pr
15:15:32 <samccann> acozine: I don't have it installed locally (tornado)
15:15:33 <felixfontein> sorry for rebasing taking so long, my machine is somehow strangely slow
15:15:44 <acozine> np
15:16:05 <acozine> samccann: you don't? interesting
15:16:38 <samccann> pip show tornado doesn't give me anything
15:17:23 <samccann> I also didn't install six, but it's there locally so it may be something like pygments that gets installed automagically by sphinx
15:18:21 <acozine> hm . . . I'll try removing tornado and doing a rebuild
15:19:39 <acozine> yep, works fine - I'll remove that from the list
15:20:07 <acozine> felixfontein: thanks for the rebase - as soon as the tests pass, I'll merge the lexers PR
15:20:35 <acozine> #topic deprecated aliases, see https://github.com/ansible/ansible/pull/57774/files
15:21:01 <acozine> felixfontein: I meant to merge this earlier in the week, so we could get resmo's PR in, but it fell off my radar
15:21:20 <acozine> is there anything tricky or troublesome about the change?
15:21:42 <felixfontein> I don't think so
15:22:01 <felixfontein> it doesn't seem to break existing stuff AFAIK, and fixes something which has been broken
15:22:14 <acozine> the best kind of PR!
15:22:31 <acozine> merged . . . and thanks for the fix
15:22:36 <felixfontein> hehe. let's hope there is no surprise ;)
15:23:25 <acozine> heh, yep
15:23:47 <acozine> still, the code can't live in amber . . .
15:24:07 <acozine> add functionality, break functionality, fix functionality, repeat
15:24:30 <felixfontein> yep
15:24:53 <acozine> #topic custom 404 and the version-changer
15:25:27 <acozine> we merged the custom 404 page this week
15:25:33 <felixfontein> ah, cool!
15:25:38 <samccann> woot woot!!
15:25:59 <felixfontein> is it already available for the devel docs?
15:25:59 <acozine> this link will show you the content: http://docs.testing.ansible.com/ansible/latest/dev_guide/index2.html
15:26:19 <acozine> felixfontein: the page is there, but the webserver is not set up to return it for 404 codes yet
15:26:45 <acozine> (in production - on the test site, it's all functioning together)
15:26:48 <felixfontein> ah ok :) at least on testing, it works fine
15:27:14 <felixfontein> so next steps: deploy this, and then merge version changer?
15:27:33 <acozine> yeah, we'd appreciate testing on the version changer on the test site
15:28:15 <acozine> the one drawback we've found is that the version-changer doesn't work on the 404 page itself - because 404s on any version return the same, single page
15:29:36 <acozine> the alternative is to set up separate ErrorDocument directives for each version, which makes the site slower and means more maintenance
15:30:25 <acozine> the version-changer works beautifully on most pages, for example: http://docs.testing.ansible.com/ansible/2.6/porting_guides/porting_guides.html
15:31:01 <felixfontein> is it possible to hide the version changer on the 404 page?
15:31:03 <acozine> and on module pages as well: http://docs.testing.ansible.com/ansible/2.7/modules/file_module.html
15:31:15 <acozine> felixfontein: hm . . . I'm not sure how
15:31:25 <acozine> samccann: any ideas?
15:31:43 <acozine> the version-changer is samccann's (excellent) work
15:31:52 <felixfontein> ah, great! thanks samccann!
15:32:05 <samccann> depends on how important we feel that 404 issue is
15:32:45 <samccann> as in, there might be some javascript we could add specifically to ignore the version changer code if the current html page is 404.html.  But then that makes that page's navigation look different too
15:33:00 <samccann> you want me to spend some cycles trying?
15:33:11 <acozine> https://github.com/ansible/ansible/pull/55655/files
15:34:16 <acozine> I don't know if it's worth it . . .
15:34:33 <acozine> faced with a 404, I generally check my URL for typos or hit the back button
15:35:07 <acozine> this is why I hoped for wider testing - if most folks don't notice, then it's not worth spending time on it
15:35:22 <acozine> but if it annoys a lot of users, then maybe it is . . .
15:35:36 <samccann> the other option is publish and yeah, if it annoys, someone will open an issue
15:35:48 <acozine> yeah, that's the direction I'm leaning toward
15:36:49 <felixfontein> I find it a bit confusing that suddenly it says "devel" as the version when you're on a 404 page
15:37:38 <acozine> in production it will be `latest` instead of `devel` but the behavior would be the same . . . unless we add multiple .htaccess files
15:38:32 <felixfontein> ah, I think that would be ok (at least for me :) )
15:38:47 <felixfontein> if they start navigating from the 404 page, they won't end up in devel land, but in latest land
15:39:17 <acozine> yeah, the idea is to subtly suggest "this page didn't exist in 2.6, perhaps you need to upgrade?"
15:39:25 <samccann> hehe
15:40:36 <acozine> I vote we give it one more day for folks to look at the test site
15:40:46 <samccann> sounds good
15:40:53 <acozine> if nothing bad comes up, we merge and deploy it tomorrow
15:41:50 <acozine> and then we refine as folks file issues
15:42:06 <samccann> +1
15:42:09 <acozine> meanwhile we can close the half-dozen or so "give us a version-switcher" issues we already have
15:42:35 <samccann> hahahaha
15:43:09 <felixfontein> sounds good :)
15:43:18 <acozine> excellent! it's a plan
15:43:22 <acozine> #topic open floor
15:43:27 <acozine> anyone have anything else?
15:44:12 * acozine exercises patience . . .
15:44:19 <samccann> general plug for folks to take a look at the easyfix issues for docs - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs+label%3Aeasyfix
15:44:46 <acozine> samccann: congratulations on the success you've had with that label - people really do look for those
15:44:49 <acozine> and open PRs
15:45:10 <samccann> \o/
15:45:47 <acozine> all right, I think that's it for today - thanks felixfontein samccann and everyone who's lurking . . .
15:45:49 <samccann> someone was mentioning that github has a fixed label for these... something like 'goodfirst_issue' but I don't see that on ansible github as an option?
15:46:04 <acozine> samccann: oh, yeah, I've seen that
15:46:21 <acozine> https://github.com/rtfd/sphinx-notfound-page/issues
15:46:38 <acozine> we could add that, or revert the `easyfix` label to that
15:46:38 <samccann> that and jstickler got them to add `documentation` as a default label
15:46:59 <bcoca> samccann: they are there, just not in labels page .. and scrolling on the pop up is crazy since we added 'every file in repo as a label'
15:47:32 <samccann> ah so we could decide to start using that instead of `easyfix`  but what about the rest of ansible?
15:47:35 <acozine> if we can ever get the backlog down to a reasonable number of open issues and PRs, we could normalize the labels and relabel open PRs to match . . . but I don't see that happening soon
15:48:45 <acozine> samccann: I see a blog post in your future . . .
15:48:56 <samccann> heh
15:50:18 <samccann> bcoca: I don't see how I can add `good first issue` label in ansible?
15:50:29 <acozine> we'd also need to reprogram ansibot to match
15:50:59 <samccann> yeah for docs... I'm just wondering if it's worth switching to good first issue or leave it as easyfix?
15:51:01 <acozine> (if we changed from `docs` to `documentation)
15:51:28 <acozine> how about we track issues marked `easyfix` for a while and see how long they linger unfixed
15:51:38 <bcoca> samccann: we might have disabled since it conflicts with the labels we use, i did see it there when they introduced them
15:51:54 <bcoca> acozine: ask jtanner, he has graphs
15:52:12 <bcoca> and .. i forget whom else, has graphs that track by label .... tanner should know
15:52:13 <samccann> yeah there are 26 `easyfix` labels in ansible today.
15:52:15 <acozine> if we find that `easyfix` issues are not getting picked up, we can delve into re-labelling them
15:52:23 <samccann> ok
15:52:32 <acozine> samccann: and how many closed `easyfix` issues?
15:52:45 <samccann> 107
15:52:56 <acozine> that's a decent ratio
15:53:02 <samccann> now how many were closed by community/new folks vs others? who knows
15:53:10 <acozine> true
15:56:48 <acozine> felixfontein: lexers PR merged
15:57:21 <acozine> samccann: let's keep track of the `easyfix` issues for a few weeks and see how it goes
15:57:42 <samccann> yeah sounds like a plan. We shouldn't change it unless all of ansible changes.
15:58:21 <acozine> thanks everybody for another good DaWGs meeting
15:58:52 <acozine> feel free to add items to next week's agenda at https://github.com/ansible/community/issues/389
15:58:57 <acozine> #endmeeting