15:32:32 <acozine> #startmeeting Docs Working Group aka DaWGs
15:32:32 <zodbot> Meeting started Tue Mar 19 15:32:32 2019 UTC.
15:32:32 <zodbot> This meeting is logged and archived in a public location.
15:32:32 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:32:32 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:32:32 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:32:36 <acozine> who's around?
15:35:18 * acozine is all alone out here on the Internet
15:35:19 * samccann waves
15:35:28 <acozine> #chairs samccann
15:35:33 <acozine> grrr
15:35:33 <samccann> all alooooone... nobody to write docs wiiiittthhh
15:35:37 <acozine> #chair samccann
15:35:37 <zodbot> Current chairs: acozine samccann
15:35:57 <acozine> exactly! Noooooooobodddddy
15:36:12 <acozine> maybe everyone else is on spring break ;)
15:36:18 <samccann> could be a short meeting!
15:36:42 * acozine wouldn't mind a spring break
15:37:32 <acozine> hm, well, we'd like to look at the proposed fix for the switching-versions problem
15:38:24 <acozine> 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 <acozine> related issues include:
15:39:02 <samccann> #topic Proposed fix for switching versions problem
15:39:15 <acozine> thanks samccann
15:39:25 <acozine> Issues related to the topic includ3e;
15:39:26 <samccann> #link  https://github.com/ansible/ansible/pull/53317
15:39:31 <acozine> https://github.com/ansible/ansible/issues/45651
15:39:45 <acozine> https://github.com/ansible/ansible/issues/41782
15:39:59 <acozine> https://github.com/ansible/ansible/issues/37049
15:40:10 <acozine> https://github.com/ansible/ansible/issues/28553
15:40:39 <acozine> for background, versioned docs started off with https://github.com/ansible/proposals/issues/60
15:42:31 <samccann> 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 <acozine> that would definitely be better, and if we only allow version-switching among currently-supported versions, it should work fairly seamlessly
15:43:13 <samccann> 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 <samccann> 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 <samccann> 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 <acozine> 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 <acozine> 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 <samccann> 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 <samccann> ok found it - https://github.com/rtfd/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/versions.html
15:52:22 <samccann> 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 <acozine> 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 <samccann> both actually
15:54:45 <acozine> ah, okay
15:54:50 <samccann> 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 <acozine> that's an interesting idea
15:55:39 <samccann> and the extensions being added - https://github.com/rtfd/readthedocs-sphinx-ext
15:55:56 <samccann> which includes a handy-dandy 'warning' banner about being on an old version of the docs :-)
15:56:12 <acozine> ah, that would be useful
15:56:49 <samccann> 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 <acozine> you want to play with that in a branch and report back to the group?
15:57:20 <acozine> that might solve both problems with minimal effort on our part
15:57:49 <acozine> (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 <samccann> 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 <samccann> but you and I can cover that offline after I experiment locally
15:59:29 <acozine> sounds good
15:59:58 <acozine> that seems like a good approach to this issue
16:00:14 <acozine> anyone else here, lurking, and have an opinion or idea to share on this topic?
16:01:17 <acozine> hearing none, we will move on to . . .
16:01:22 <acozine> #topic open floor
16:01:42 <acozine> anyone can bring up anything - pending PRs, open issues, questions, concerns
16:02:26 <acozine> I think this is going to be our shortest meeting ever
16:02:41 <samccann> :-)  maybe it is spring break!
16:02:58 <samccann> 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 <acozine> all right, folks
16:04:19 <acozine> 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 <acozine> 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 <acozine> everyone is welcome
16:05:20 <acozine> #endmeeting