15:32:32 #startmeeting Docs Working Group aka DaWGs 15:32:32 Meeting started Tue Mar 19 15:32:32 2019 UTC. 15:32:32 This meeting is logged and archived in a public location. 15:32:32 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:32:32 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:32:32 The meeting name has been set to 'docs_working_group_aka_dawgs' 15:32:36 who's around? 15:35:18 * acozine is all alone out here on the Internet 15:35:19 * samccann waves 15:35:28 #chairs samccann 15:35:33 grrr 15:35:33 all alooooone... nobody to write docs wiiiittthhh 15:35:37 #chair samccann 15:35:37 Current chairs: acozine samccann 15:35:57 exactly! Noooooooobodddddy 15:36:12 maybe everyone else is on spring break ;) 15:36:18 could be a short meeting! 15:36:42 * acozine wouldn't mind a spring break 15:37:32 hm, well, we'd like to look at the proposed fix for the switching-versions problem 15:38:24 starting with https://github.com/ansible/ansible/pull/53317 as a possible solution, and discussing what's good about it, what could be improved, etc. 15:38:32 related issues include: 15:39:02 #topic Proposed fix for switching versions problem 15:39:15 thanks samccann 15:39:25 Issues related to the topic includ3e; 15:39:26 #link https://github.com/ansible/ansible/pull/53317 15:39:31 https://github.com/ansible/ansible/issues/45651 15:39:45 https://github.com/ansible/ansible/issues/41782 15:39:59 https://github.com/ansible/ansible/issues/37049 15:40:10 https://github.com/ansible/ansible/issues/28553 15:40:39 for background, versioned docs started off with https://github.com/ansible/proposals/issues/60 15:42:31 there were a couple of issues with the proposed fix. The critical one is that it currently goes to the main docs index page of the selected version. It would be better if it went to the same 'page' it was on in the selected version (if that page exists) 15:43:11 that would definitely be better, and if we only allow version-switching among currently-supported versions, it should work fairly seamlessly 15:43:13 The other issue was a debate on whether it should move the 'selected version' option to the top of the left-hand navigation. It's currently at the bottom. I'm fifty-fifty on whether this needs to change or not 15:43:50 the readthedocs sites that this snippet is coming from all have versions at the bottom. Dunno how easy/hard it would be to move it. 15:45:21 you can see that snippet in action on another docsite here - https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html 15:46:39 for the "switch-to-the-equivalent-page" problem, would it work to change `index.html` to `{{ page_name }}` at https://github.com/ansible/ansible/pull/53317/files#diff-05d6794f934a4f85a42c0089ed4769b7R48 ? 15:48:40 samccann: putting the switch mechanism in the upper left where users are used to seeing the version number makes sense for UX continuity 15:49:10 trying to find how the readthedocs docs handle it. I'm pretty sure that site keeps the page URL as it switches versions 15:51:47 ok found it - https://github.com/rtfd/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/versions.html 15:52:22 so as a side discussion - our build has a copy of the sphinx_rtd_theme, not using the existing theme (and it's improvments). 15:53:50 samccann: you mean, there's a more recent theme than the one we have? or you mean we should be symlinking in some way instead of copying the theme, so we take advantage of improvements sooner? 15:54:20 both actually 15:54:45 ah, okay 15:54:50 our copy is old, and yes, other docsites build directly from the theme 'upstream' so to speak, to keep up with what's being improved up yondar 15:55:15 that's an interesting idea 15:55:39 and the extensions being added - https://github.com/rtfd/readthedocs-sphinx-ext 15:55:56 which includes a handy-dandy 'warning' banner about being on an old version of the docs :-) 15:56:12 ah, that would be useful 15:56:49 if I understand it correctly (and I likely don't) you install the theme and the theme extensions, much like you install sphinx to run the build. Now I dunno how this integrates into the build that goes to docs.ansible.com 15:57:06 you want to play with that in a branch and report back to the group? 15:57:20 that might solve both problems with minimal effort on our part 15:57:49 (where "both problems" means telling users when they're looking at outdated docs, and allowing users to switch versions in a sensible way) 15:58:32 sure I can do this locally, but I dunno how /where the actual docsite builds from to publish to docs.ansible.com. 15:59:22 but you and I can cover that offline after I experiment locally 15:59:29 sounds good 15:59:58 that seems like a good approach to this issue 16:00:14 anyone else here, lurking, and have an opinion or idea to share on this topic? 16:01:17 hearing none, we will move on to . . . 16:01:22 #topic open floor 16:01:42 anyone can bring up anything - pending PRs, open issues, questions, concerns 16:02:26 I think this is going to be our shortest meeting ever 16:02:41 :-) maybe it is spring break! 16:02:58 was last week for my son but who knows...at least this week IS the start of spring 16:03:18 * acozine is going to spend the rest of the meeting in the wan spring sunlight of a Minnesota March 16:03:31 all right, folks 16:04:19 as a reminder, topics for the weekly DaWGs / Docs Working Group meeting can be added to the bottom of https://github.com/ansible/community/issues/389 16:04:55 if you have a question about Ansible documentation, a PR you'd like reviewed, an issue to dig into, or want to make a contribution, this is the place! 16:05:09 everyone is welcome 16:05:20 #endmeeting