15:31:30 <gundalow> #startmeeting Ansible Documentation Working Group
15:31:30 <zodbot> Meeting started Tue Nov 13 15:31:30 2018 UTC.
15:31:30 <zodbot> This meeting is logged and archived in a public location.
15:31:30 <zodbot> The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:31:30 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:31:30 <zodbot> The meeting name has been set to 'ansible_documentation_working_group'
15:31:51 <gundalow> #chair acozine samccann felixfontein
15:31:51 <zodbot> Current chairs: acozine felixfontein gundalow samccann
15:32:55 <acozine> Good <time_period>, folks!
15:33:29 <acozine> heh, I guess I should express that as "Good {{ time_period }}"
15:34:14 <gundalow> Who else is around?
15:34:19 <Xaroth> o7
15:34:25 <gundalow> #chair Xaroth
15:34:25 <zodbot> Current chairs: Xaroth acozine felixfontein gundalow samccann
15:34:47 <samccann> :-)
15:36:35 <gundalow> #info Agenda https://github.com/ansible/community/issues/389
15:36:48 <gundalow> acozine: Would you like to `#topic foo`?
15:36:57 <acozine> #topic breadcrumbs proposal
15:37:03 <acozine> #info https://github.com/ansible/community/issues/389#issuecomment-436319168
15:37:09 <acozine> grrr
15:37:13 <acozine> not that ^^^
15:37:17 <gundalow> #undo
15:37:17 <zodbot> Removing item from minutes: INFO by acozine at 15:37:03 : https://github.com/ansible/community/issues/389#issuecomment-436319168
15:37:41 <acozine> #info https://github.com/ansible/proposals/issues/147
15:37:46 <acozine> thanks gundalow
15:38:38 <acozine> I've been thinking a bunch recently about changes to the docsite that would improve it
15:38:54 <gundalow> What would this look like for Modules?
15:39:12 <gundalow> `Ansible >> modules >> network >> vyos >> vyos_command`
15:39:37 <acozine> yeah, that looks good, though some module names are pretty long
15:39:50 <acozine> so I don't know if all of that would git
15:39:53 <acozine> s/git/fit
15:40:09 <bcoca> acozine: ++ for using git in a sentence
15:40:25 <gundalow> #chair bcoca
15:40:25 <zodbot> Current chairs: Xaroth acozine bcoca felixfontein gundalow samccann
15:41:10 <samccann> +1 for the breadcrumbs
15:41:24 <gundalow> Longest directory (foo/bar) is 34 characters
15:41:39 <gundalow> 71 for foo/bar/bar_moo.py
15:42:42 <gundalow> So I think that's OK
15:42:50 <acozine> so 105 characters of text, plus the spaces, plus `ansible` and `modules`
15:42:54 <gundalow> In the future we could look at trimmining it
15:42:54 <acozine> yeah, that seems okay
15:42:58 <samccann> if the module names are too long, could we stop the breadcrumbs at 'vyos' in the example above?
15:43:39 <acozine> I think so . . . unless people actually use that to remind themselves where they are in the docs?
15:43:45 <acozine> it doesn't make sense as a link
15:44:04 <acozine> I mean, why offer a link to the page you're already on?
15:44:36 <samccann> personally, I use breadcrumbs to 'get back' to something prior to what I'm currently looking at
15:44:53 <gundalow> Being able to go from vyos_command to list of all vyos modules would be really useful
15:45:02 <acozine> I could also see using them to find related content
15:45:03 <samccann> so if I'm on a specific module, maybe it's not the one I want, so I want to go back to the full list of vyos modules to find another one
15:45:13 <acozine> yeah
15:45:40 <acozine> even if you got to the current page some other way, like from search results
15:45:52 <Xaroth> +1 for breadcrumbs, module navigation currently is quite tedious
15:45:59 <gundalow> #info Currently longest directory+ module is 67 which is `remote_management/oneview/oneview_logical_interconnect_group_facts`
15:46:48 <gundalow> For non-modules would the breadcrumbs be the directory?
15:47:40 <acozine> For non-modules maybe `Ansible >> Guide_Name >> Page_Name`?
15:49:03 <acozine> offering links to related content, as `gitqlt` suggests, would be great
15:49:18 <acozine> but we don't currently have a hierarchy we can build from
15:50:02 <gundalow> I wonder if we could start with one place and then roll it out to others
15:51:57 <acozine> I think we could make the breadcrumbs match the directory structure site-wide
15:52:04 <acozine> that would give us the full fix on module docs
15:52:10 <acozine> and the partial fix on the other pages
15:52:13 <gundalow> ie modifying https://github.com/ansible/ansible/blob/devel/docs/templates/plugin.rst.j2 should give us breadcrums for modules
15:52:59 <acozine> will it?
15:53:09 <acozine> here I will display my ignorance and appeal for help
15:53:25 <acozine> I don't know how those breadcrumbs are constructed, or where
15:53:29 <gundalow> primary_category + primary_category are already passed into that template
15:53:55 <bcoca> gundalow: i believe we used to have breadcrumbs in subheader, but those never worked correctly
15:53:59 <gundalow> hum, I should look at the existing code
15:54:11 <bcoca> for modules/plugins, yes we can use that template, but shouldn't we look at something more 'site wide'?
15:54:33 <acozine> bcoca: site-wide would be my preference
15:55:07 <gundalow> ` »` isn't defined in our code, so I assume it must be Sphinx
15:55:12 <acozine> at least to start with - less room for duplication and confusion
15:55:15 <gundalow> I incorrectly assumed it was something we were doing
15:55:19 <bcoca> i mean, module pages are 80% of the site ... but still i would look at something in the header file (maybe something we update from plugins.rst's js)
15:57:13 <acozine> answer here: https://stackoverflow.com/questions/38797704/how-do-sphinx-configurations-setup-breadcrumbs suggests that the breadcrumbs are set in `layout.html`
15:57:52 <bcoca> we have 3 layout.html .. that might be part of the issue
15:57:58 <acozine> heh
15:58:02 <acozine> yeah
15:58:13 <bcoca> docsite/_themes/sphinx_rtd_theme/layout.html
15:58:15 <bcoca> docsite/_themes/srtd/layout.html
15:58:16 <bcoca> docsite/rst/dev_guide/style_guide/_themes/srtd/layout.html
15:58:37 <acozine> okay, I will take on the task of turning the breadcrumbs proposal into a ticket
15:58:39 <bcoca> i remember modifying at least one of those (not dev_guide)
15:58:56 <acozine> actually it will be part of an epic about cleaning up the sphinx themes
15:58:58 <gundalow> I was (possibly incorrectly) thinking we could update `plugin.rst.js` to have something like `Docs  » Modules  » :ref`@{ categories }@ » :ref`@{ primary_categories }@ » @{ module }@`
15:59:33 <acozine> gundalow: then wouldn't we end up with two sets of breadcrumbs?
15:59:33 <bcoca> gundalow: probably you can, im unsure, I was just looking to do whole site
15:59:46 <gundalow> acozine: yup, though we could remove from top
15:59:55 <bcoca> i mean, you had me at 'breadcrumbs' .. its something i've wanted working on the site for 5yrs
15:59:57 <gundalow> though more I'm thinking maybe I'm "doing it wrong"
16:00:26 <felixfontein> (sorry, I'm mostly afk, I'll only read this afterwards... too busy with other stuff...)
16:00:27 <acozine> I really don't want to have "special formatting" for individual sections if we can avoid it
16:02:03 <acozine> #action acozine to write up a ticket to cover CSS changes, including breadcrumbs and de-duplicating the Sphinx themes
16:02:24 <gundalow> #info https://stackoverflow.com/questions/38797704/how-do-sphinx-configurations-setup-breadcrumbs?rq=1 may have some useful ideas in
16:02:51 <acozine> I'll close the proposal with a link to the new ticket
16:03:01 <acozine> gundalow: that looks interesting indeed
16:03:55 <acozine> oh, does anyone understand `kolibri`'s comment on the proposal?
16:04:06 <acozine> "The module pages also have another problem: They don't collapse the navigation on the left side. So, even if you are on a modules page, you have to collapse the menu to get to the categories."
16:04:34 <bcoca> yeah, the left nav has always been 'disociated' from the in page navigation
16:04:50 <bcoca> but breadcrumbs might not solve that unless we sync those .. which im fine with not doing
16:06:35 <acozine> I'm not sure what the commenter wants, but I'm happy to do the bigger thing I do understand and then see if folks suggest more improvements over that
16:07:20 <acozine> anything else on breadcrumbs?
16:08:01 <acozine> hearing none . . .
16:08:13 <acozine> #topic recent PRs
16:09:08 <acozine> This one hasn't been backported (or even published) yet, but I think it will be helpful
16:09:11 <acozine> https://github.com/ansible/ansible/pull/48436
16:09:42 <acozine> details how to run the Sanity tests locally and why running `make clean` is helpful when testing docs changes
16:11:04 <gundalow> Nice :)
16:12:01 <Xaroth> I like the concept of documentation of the tests that test on documentation changes.
16:12:15 <acozine> it's testing and documentation all the way down
16:12:28 <acozine> document, test, repeat
16:12:34 <acozine> or maybe test, document, repeat
16:12:37 <acozine> hard to tell
16:13:02 <acozine> then there's this one: https://github.com/ansible/ansible/pull/48379
16:13:31 <acozine> a nice catch - updates a really old bit of documentation
16:13:59 <acozine> anyone else have PRs to highlight?
16:14:23 <acozine> Could be open PRs for review, or closed ones for kudos/distribution
16:14:37 <gundalow> acozine: https://github.com/ansible/ansible/labels/docsite lists PR that change `docs/docsite`
16:15:05 <acozine> gundalow: thanks
16:15:32 <gundalow> Which is something I believe you were interested in, rather than `label/docs` which lists anything under `./docs` PLUS and PR that someone lists as updating (module/plugin) docs
16:16:13 <acozine> do we also still have the `docsite_pr` label?
16:16:19 <gundalow> hum, that list looks incomplete stuff, maybe Bot needs another few days to walk over things
16:16:25 <gundalow> `docsite_pr` hasn't been changed
16:17:07 <acozine> how would folks feel about changing `docsite_pr` to `web_edited` or something similar?
16:18:52 <gundalow> Works for me
16:19:04 <acozine> gundalow: ansibot will catch up
16:19:10 <gundalow> yup
16:20:54 <acozine> we've got ten minutes left
16:21:05 <acozine> anything else on PRs to highlight?
16:21:21 <acozine> #topic open floor
16:21:43 <gundalow> Nothing else from me
16:21:58 <acozine> anybody got stuff going on?
16:23:32 * gundalow is going to start on https://docs.google.com/document/d/1nMevQ0W7MZgJA1tJrJbNHIhTiHYHYUlO3IHXBs_usGE/edit#heading=h.5um7ye363cxd this week
16:23:55 <gundalow> Though need to make sure I don't end up trying to rewrite everything :)
16:24:07 <acozine> so tempting!
16:24:18 <acozine> baby steps where possible!
16:24:29 <gundalow> Yup :)
16:25:52 <gundalow> Nothing else from me
16:25:57 <acozine> looks like that's it, DaWGs
16:26:10 <gundalow> Thanks y'all
16:26:15 <gundalow> #endmeeting