15:30:56 <acozine> #startmeeting DaWGs aka Docs Working Group
15:30:56 <zodbot> Meeting started Tue Apr 23 15:30:56 2019 UTC.
15:30:56 <zodbot> This meeting is logged and archived in a public location.
15:30:56 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:30:56 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:30:56 <zodbot> The meeting name has been set to 'dawgs_aka_docs_working_group'
15:31:28 <acozine> who's around?
15:31:36 * samccann waves
15:31:36 <acozine> #chair Xaroth samccann
15:31:36 <zodbot> Current chairs: Xaroth acozine samccann
15:33:04 <acozine> felixfontein: decentral1se Pilou dag  you around? we're looking at a new version-changer option and a speed enhancement to the docs build
15:34:05 <Pilou> o/
15:34:12 <acozine> #chair Pilou
15:34:12 <zodbot> Current chairs: Pilou Xaroth acozine samccann
15:34:22 <acozine> Pilou: hey, welcome back!
15:35:09 <acozine> so the results of both PRs under consideration are published to the test site
15:35:22 <acozine> http://docs.testing.ansible.com/ansible/latest/community/index.html
15:35:48 <acozine> the current suggestion for speeding up the build is a change to the table of contents
15:36:11 <acozine> it removes the little + signs next to the top-level headers in the left navigation bar
15:36:38 <acozine> so you can't, for example, expand the TOC for the Developer Guide without actually moving to the index page for that section
15:36:55 <samccann> local builds (for me) happen in 6 minutes on my laptop vs 20 minutes. YMMV
15:37:01 <samccann> (make webdocs builds to be clear)
15:37:38 <acozine> PR is at https://github.com/ansible/ansible/pull/55593
15:38:18 <acozine> what do folks think?
15:38:24 * gundalow waves
15:38:30 <acozine> #chair gundalow
15:38:30 <zodbot> Current chairs: Pilou Xaroth acozine gundalow samccann
15:38:31 <gundalow> (just in another meeting at the moment)
15:38:32 <Pilou> Could not a '+' sign be added to every entries ?
15:38:53 <samccann> the code that adds that + sign also slows down the build considerably.
15:39:20 <acozine> what the '+' sign means is that that entire TOC section gets built on every page - that's how we do it now
15:39:39 <Pilou> I mean, just a visual information implying there are submenus
15:39:41 <acozine> Pilou: for comparison, see https://docs.ansible.com/ansible/devel/community/index.html
15:40:03 <acozine> Pilou: ah, a kind of fake plus sign
15:40:07 <Pilou> yep
15:40:07 <acozine> that's a cool idea
15:40:13 <samccann> also, besides the local speedup,  this pr would help us get toward including more automated testing on docs.. (something we can't do today because it takes so long)
15:40:44 <acozine> so it would still function differently, but it would look more like it does now
15:40:54 <samccann> hmmm
15:41:36 <samccann> not sure what that buys you?  if you click on a section, it expands if there is more there... it just also refreshes the page (which it didn't do)
15:42:55 <acozine> all top-level sections have more content . . . but maybe a new user wouldn't guess that? is that what you're worried about PIlou?
15:44:25 <Pilou> yep
15:44:48 <acozine> I don't believe the Sphinx theme offers that out of the box, but we could investigate
15:45:35 <acozine> it would be cool if we could do it, but I don't see it as a blocker - how do others feel about the tradeoffs?
15:45:41 <samccann> there's also the side effect -the existing plus sign does something (expand collapse). Adding a fake plus sign image could frustrate someone expecting expand/collapse.
15:46:07 <acozine> samccann: yeah, it would definitely have to be part of the clickable region
15:46:21 <acozine> so if you clicked there, it would move you to the new page and expand the TOC
15:46:31 <acozine> I guess that might be misleading/frustrating
15:46:54 <acozine> gundalow: thoughts on this?
15:46:54 <Pilou> otherwise could the '+' always hidden ? (it appears when clicking on the '-')
15:47:52 <samccann> something we could investigate. It's likely buried in the theme we 'borrow' from readthedocs
15:48:19 <samccann> our version of that theme is quite old, so that might be a good 'next step' is get the most recent version and see what happens
15:49:57 <acozine> okay, let's look at the other feature on the test site
15:50:07 <acozine> and circle back
15:50:28 <samccann> before we shift off
15:50:49 <samccann> are we okay to merge the speedup? with the understanding that we investigate the lingering + sign?
15:50:59 <samccann> (post merge...cuz I think it's a bigger issue)
15:51:14 <samccann> or do we want to hold off on the speed PR until we dig into the + sign
15:51:27 <acozine> I'm +1 on merging and addressing the + sign separately
15:51:56 <acozine> Pilou: are you +1, -1, or 0 on merging what we have so far?
15:52:06 <Pilou> +1
15:52:23 <acozine> awesome, anybody else want to vote?
15:52:43 <samccann> (me too but it's my PR so...keeping mum)
15:52:51 <acozine> samccann: you get a vote
15:52:59 <samccann> +1  merge all the things!!!
15:53:03 <acozine> so far we are at 3/0/0
15:53:09 <acozine> going once . . .
15:53:12 <acozine> going twice . . .
15:53:39 * acozine forces herself to be patient . . . patience, how long will that take?
15:53:53 <samccann> patiently awaiting patience?
15:54:03 <acozine> MERGED!
15:54:09 <samccann> \o/
15:54:31 <acozine> samccann: there's an old comedy skit about martial arts
15:55:29 <acozine> http://dmdb.org/lyrics/boot.to.the.head.html
15:55:36 <acozine> but I digress . . .
15:56:31 <acozine> okay, the other change on the test site is from a separate PR
15:56:55 <acozine> if you look at the bottom of the left nav on any page in `latest`
15:57:03 <samccann> #topic version dropdown on docsite
15:57:07 <acozine> like, for example http://docs.testing.ansible.com/ansible/latest/user_guide/index.html
15:57:12 <acozine> samccann: heh, thanks
15:57:29 <samccann> #link https://github.com/ansible/ansible/pull/55655
15:57:30 * acozine forgets the IRC stuff too often
15:57:36 <samccann> yeah same here!
15:57:48 <acozine> so you'll see a version-changer at the bottom of the left nav
15:57:55 <acozine> right now it's only on that one branch
15:58:04 <acozine> so you can change to 2.6 and then change back
15:58:10 <acozine> s/can/can't
15:58:39 <gundalow> (on Previoustopic https://github.com/ansible/ansible/pull/55593 could that get published to test server so we can compare and see how the expansion works)
15:58:53 <samccann> it's there already
15:58:54 <acozine> gundalow: it's published there now
16:01:41 <acozine> I'd still like to see the version-changer appear higher up, instead of at the bottom
16:02:10 <acozine> this is related to a bunch of issues, including https://github.com/ansible/ansible/issues/45651
16:02:25 <acozine> https://github.com/ansible/ansible/issues/41782
16:02:38 <acozine> https://github.com/ansible/ansible/issues/37049
16:02:52 <samccann> I'm not sure it can be done with the version.html we are again borrowing from the sphinx theme.  But based on that, maybe we can create our own code?  not sure the complexity
16:03:08 <samccann> I tried some 'simple things' yesterday and nothing worked.. but that was just an hr or so of banging on it.
16:03:21 <Pilou> at the top of the left nav, is "Ansible devel" mentioned when "latest" is selected because the branch isn't merged ?
16:04:03 <samccann> Pilou I believe so, yes.
16:04:25 <acozine> Pilou: ah, we must have published it with the symlink set . . . so right now the `devel` branch *is* `latest` on the test site . . .
16:04:31 <acozine> but only on the test site
16:05:02 <samccann> yeah that's my thought.  that said...not sure how to test that hypothesis?
16:05:33 <acozine> we could republish the same branch with that last parameter on the Jenkins job switched
16:05:36 <samccann> I can't test this at all locally because the local build html doesn't include a version
16:05:58 <samccann> okay show me after the meeting and I can give it a try
16:06:06 <acozine> samccann: sounds good
16:06:51 <acozine> for anyone who's interested in the nuts and bolts . . .
16:07:32 <acozine> the publication pipeline sets that docsite URL to `devel` for the devel branch and to the output of `ansible --version`, truncated to two digits, for all other branches
16:07:56 <acozine> the `latest` URL is a symlink that can be set to any other URL
16:08:10 <acozine> so on the production site right now, `latest` points to `2.7`
16:08:22 <acozine> but we can control that in the build
16:08:31 <samccann> acozine Pilou - it might be an error in the PR code itself.  I set a parameter to 'latest'
16:08:54 <acozine> samccann: oh, good to know
16:09:00 <acozine> that will need ironing out
16:09:11 <samccann> I may need to set that differently on each branch.. .aka should be `devel` for this PR, and then `latest` in 2.8 backport, `2.7` in 2.7 etc etc.  needs more testing
16:09:18 <samccann> so thanks for that catch!
16:10:46 <acozine> anybody else have comments? suggestions? ideas?
16:10:49 <acozine> complaints?
16:11:18 <samccann> how strongly do folks feel about moving up to the top(ish) vs floating at the bottom where it is now?
16:11:41 <acozine> I know dag mentioned that on the original PR
16:11:44 <samccann> keeping in mind we'd be leaving the sphinx theme behind if we do this
16:12:04 <samccann> yeah I favor it up at the top myself, but I worry about ^^
16:12:09 <acozine> I think it's worth a day of work to understand the maintenance burden
16:12:30 <samccann> ok I'll keep plugging away
16:12:30 <acozine> once we know how far we'd have to move away from the sphinx theme, we can make an informed decision about the tradeoffs
16:13:19 <samccann> sounds good
16:13:30 <acozine> #topic open floor
16:13:50 <acozine> anybody have a PR they'd like to move forward?
16:14:01 <acozine> or an issue they'd like to discuss?
16:14:05 <samccann> #agreed -continue to experiment with version change PR to move the selection higher up the left-hand navigation
16:14:59 <Pilou> there is #50278
16:15:31 <acozine> #topic https://github.com/ansible/ansible/issues/50278
16:15:42 <Pilou> i am not sure if a resolution has been choosen
16:15:51 <acozine> thanks for bringing it up
16:16:24 * acozine reads the issue, humming a bit to herself
16:16:36 <dag> acozine: Related to TOC, IMO best thing would be to build the TOC dynamically, but that requires an advanced theme that can do that
16:16:53 <acozine> dag: do you know of one out there?
16:17:06 <dag> acozine: no
16:17:16 <acozine> bummer
16:18:59 <dag> another option is that the TOC is generated once, and included in each document
16:19:15 <dag> would probably be better than javascript (but less efficient)
16:19:20 <acozine> Pilou: based on sivel's comment, I think that issue is recognized as a bug: https://github.com/ansible/ansible/issues/50278#issuecomment-451186694
16:20:14 <acozine> since a code fix hasn't gone in yet, we can document the current behavior
16:20:43 <acozine> probably not an FAQ, maybe something on the Import/Includes page?
16:21:03 <acozine> dag: less efficient than javascript, or less efficient than what we have now?
16:21:07 <Pilou> sivel's comment is about a detail (task name)
16:21:41 <dag> acozine: less efficient than javascript, but offers better compatibility
16:21:52 <acozine> Pilou: ah, okay
16:22:10 <acozine> Pilou: I don't think we can fix the issue with documentation, though, do you?
16:23:06 <acozine> Pilou: we can document the current behavior, but at heart it's not a problem with the documentation
16:23:08 <Pilou> not sure if "role vars" behavior is documented
16:24:04 <Xaroth> The TOC contributes to quite a bit of disk size that the docs generate, but not really the speed
16:24:25 <sivel> I think we may have decided that #50278 is not a bug
16:24:30 <Pilou> and should not "role params" be used in examples (meaning revert the mentioned commit) ?
16:24:40 <sivel> but we are all in a m eeting right now, so I'm going back to not paying attention here
16:24:57 <acozine> Xaroth: you don't see a difference in build speed between the current `devel` branch and samccann's branch with the TOC changes?
16:25:05 <Xaroth> well, you see a bit
16:25:30 <Xaroth> but it has to be kept in mind that generating 2500+ separate pages, is going to take a while
16:26:04 <samccann> Xaroth really?  hmm.. acozine maybe you can do a build on devel and see. I assumed since my local make webdocs had dramatic speed improvement and the jenkins build also had dramatic speed improvement it would work for others.
16:26:37 <samccann> i did make clean then make webdocs
16:26:42 <Xaroth> It could be related to the env  I was testing on
16:26:50 <Xaroth> it's not that high on the iops
16:27:10 <acozine> PIlou: I'll put a note on #50278 about documenting role vars and put the docs label on it
16:27:29 <Pilou> quoting bcoca "15-01-2019 16:56:13 <bcoca> actually i believe that is a bug"
16:27:31 <Xaroth> I'll run some more tests on an iops-rich environment
16:27:41 <samccann> Xaroth - I went just by how long it takes to complete on my laptop and on jenkins test build
16:27:42 <acozine> hey, we've got three minutes left for today
16:27:57 * Pilou looking for a link to the previous discussion
16:28:32 <Xaroth> samccann: I'll do some more checks tomorrow and get back to you
16:28:39 <acozine> How would people feel about moving this meeting half an hour earlier?
16:28:58 <samccann> thanks Xaroth
16:29:01 <acozine> it's scheduled in UTC, and now that the US has changed to summer time, it conflicts with another meeting I'm supposed to be in
16:29:04 <Xaroth> don't want to write off my lack of seeing the same results to it not working, when it could realistically be my environment just being... meh :P
16:29:06 <samccann> i'm fine with earlier
16:29:26 <Xaroth> acozine: earlier works here.
16:29:42 <acozine> Pilou Xaroth dag felixfontein gundalow you're all in UK/EU, I believe, would earlier be okay? better?
16:31:10 <Xaroth> right, time to shoot some arrows. o7
16:31:21 <acozine> well, I'm not hearing objections, so I think we'll move it a bit earlier next week
16:31:24 <acozine> Xaroth: enjoy!
16:31:45 <Xaroth> endure would be more apt, still sore from the tournament of last Sunday :|
16:31:48 <Xaroth> but thanks! :D
16:31:56 <acozine> Thanks Pilou samccann gundalow dag Xaroth and everyone else who quietly followed along!
16:32:15 <acozine> #endmeeting