15:30:35 <acozine> #startmeeting Docs Working Group
15:30:35 <zodbot> Meeting started Tue Apr  9 15:30:35 2019 UTC.
15:30:35 <zodbot> This meeting is logged and archived in a public location.
15:30:35 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:30:35 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:30:35 <zodbot> The meeting name has been set to 'docs_working_group'
15:30:42 <acozine> who's around?
15:31:11 <felixfontein> hi
15:31:12 <samccann> o7
15:31:25 <acozine> #chair felixfontein samccann
15:31:25 <zodbot> Current chairs: acozine felixfontein samccann
15:31:59 <acozine> alongchamps decentral1se Xaroth you folks running with the DaWGs today?
15:32:04 <felixfontein> isn't it April 9 today?
15:32:17 <acozine> yes, is that significant?
15:32:27 <alongchamps> I'm here
15:32:27 <felixfontein> https://github.com/ansible/community/issues/389#issuecomment-480994377 says yesterday :)
15:32:37 <acozine> heh, my mistake
15:32:42 <acozine> #chair alongchamps
15:32:42 <zodbot> Current chairs: acozine alongchamps felixfontein samccann
15:32:43 <felixfontein> no problem, I only noticed now ;)
15:32:54 <acozine> I'll fix it, give me a sec
15:33:30 <felixfontein> gundalow: are you around?
15:34:28 * gundalow waves
15:34:36 <acozine> #chair gundalow
15:34:36 <zodbot> Current chairs: acozine alongchamps felixfontein gundalow samccann
15:35:21 <acozine> to anyone who is watching the chat and feeling shy - I hope you will participate
15:35:28 <bcoca> no
15:35:33 <bcoca> ;-p
15:35:40 <acozine> and IM me if you have questions you'd like to ask privately
15:35:57 <acozine> bcoca: heh, no chair for you, then
15:36:08 <bcoca> .chair
15:36:08 <zodbot> bcoca: (chair <an alias, 1 argument>) -- Alias for "echo $1 is seated in a chair with a nice view of a placid lake, unsuspecting that another chair is about to be slammed into them.".
15:36:08 <acozine> okay, our first topic today is https://github.com/ansible/ansible/pull/54448
15:36:37 <acozine> wow, zodbot is a little paranoid
15:37:15 <gundalow> acozine: I've not tested it, though PR looks good
15:37:16 <bcoca> ^ we had avoided doing this previouslly to 'discourage' aliases, ansible-doc resolves alias and presents actual module
15:37:30 <gundalow> bcoca: problem is we have broken docs links
15:37:42 <felixfontein> especially due to renames
15:37:43 <bcoca> well, deprecated were supposed to (but never got) a redirect
15:37:57 <gundalow> is latest/foo_module.html may have worked when latest=2.6, though breaks when latest=2.7
15:37:58 <bcoca> which is a special case of  aliases
15:38:35 <acozine> bcoca: do you think the policy worked to discourage aliases?
15:38:36 <felixfontein> a redirect is fine for me too, but it seems that a stub page is easier to implement
15:38:38 <bcoca> so i would treat alias != deprecated
15:38:55 <gundalow> redirects area paint to do, they live in a separate repo
15:38:58 <bcoca> acozine: mostly, since there are almost no aliases that did not come from deprecation/rename in repo
15:39:31 <felixfontein> what happens if a module changes its "main name" (so the old name becomes an alias, the old alias the new name) from one version to the next? some kind of redirect / stub page would help to avoid broken links then
15:39:36 <acozine> bcoca: okay, that's good, but the deprecation/rename ones are leaving users hanging
15:40:03 <felixfontein> (I don't even know of any module alias which is not deprecation)
15:40:13 <bcoca> im not saying we dont add a way for them to connect, just that we might want to make a clear distinction between 'normal alias' and 'rename temp alias'
15:40:35 <bcoca> felixfontein: there used to be a couple, but i think we removed all ... agian 'discouraged'
15:40:43 <acozine> bcoca: gotcha, so enforce "only deprecated modules are allowed to get aliases"
15:40:45 <bcoca> but its still possible for users to have em
15:41:03 <felixfontein> i.e. modules outside of ansible/ansible?
15:41:05 <bcoca> acozine: not really, i would make sure 'deprecated' get a page, but 'alias' get symlink to orig?
15:41:24 <bcoca> ^ users also use docsite to build with their own custom modules internally, we have no control on 'alias policy' there
15:42:19 <felixfontein> is there a way to create redirects out of sphinx?
15:42:30 <bcoca> <meta refresh ...>
15:42:35 <bcoca> or just symlink
15:42:40 <acozine> bcoca: ah, good point about local modules - so what would you change about the PR we're considering?
15:43:08 <acozine> samccann: where's that link about Sphinx redirects/aliases you found the other day?
15:43:11 <bcoca> use current template for 'deprecated/renamed' which we can detect, and make 'non deprecated alias' a redirect w/o anything to display
15:43:28 <felixfontein> bcoca: can you add <head> elements from .rst files?
15:43:49 <felixfontein> bcoca: and does sphinx convert symlinked .rst files to symlinked .html files?
15:44:10 <bcoca> felixfontein:  er .. its a symlink, do to html not rst
15:44:17 <bcoca> rst files dont make it into site
15:44:38 <samccann> acozine: https://tech.signavio.com/2017/managing-sphinx-redirects
15:44:41 <felixfontein> bcoca: but that would require major change of how the site is built. currently modules/plugins/... are only processed once to generate .rst files
15:45:01 <felixfontein> so if it's possible to do this with the .rst files, that's way simpler :)
15:45:07 <bcoca> you are modifying WHAT generates rst files ...
15:45:25 <bcoca> i disagree, but since its your patch, fine if you do via rst
15:45:45 <bcoca> i jsut find it simpler to create symlink to  module_<name>.html
15:45:48 <felixfontein> bcoca: I'm just wondering whether it is possible to do this without having to modify later parts of the build process
15:46:11 <bcoca> these files would be ignored by the build, but not by the transfer/webserver
15:46:47 <felixfontein> ah, you mean putting the .html files directly into the output directory?
15:46:58 <bcoca> but again, do what you think is simpler for you, i was just thinking 'bypass all and use symlink' as simplest solution
15:47:13 <bcoca> no, putting symlink to html , html will be result of build process
15:47:25 <bcoca> you just KNOW what name it will have at that point
15:47:33 <felixfontein> that's what I meant
15:47:50 <bcoca> but if you dont think that is simpler, anythign that gets us there works4me
15:48:17 <felixfontein> if it can be done by the same script which creates the .rst files, I'm for it
15:48:34 <felixfontein> I don't have much experience with Sphinx
15:48:50 <bcoca> dont need sphinx to do anything, just need to create symlink in right location
15:49:03 <bcoca> sphinx is out of the loop at that point
15:49:03 <felixfontein> so do we want redirects only for aliases, or for both aliases and deprecation (i.e. no stub page at all)?
15:49:13 <bcoca> i would use stub for deprecation
15:49:28 <bcoca> or make it a 302 (temp redirect)
15:49:31 <acozine> bcoca: I'm curious, why?
15:49:45 <bcoca> to allow users to know there was a specific rename and why
15:49:54 <bcoca> but i consider that 'optional'
15:50:04 <acozine> ah, so they see the old page and have to click to get to the new page?
15:50:06 <acozine> that makes sense
15:50:18 <bcoca> synlink works in both cases, perm and temp redirects 301/302 might be more 'correct' but that is really nitpicking
15:50:24 <acozine> a little education along with the redirection
15:50:48 <bcoca> in the end, user ends up in 'correct doc page' , having stub helps with 'confusion for mymodule anding up in newmodulename'
15:51:35 <acozine> felixfontein: do you have what you need to take the next steps on the PR?
15:51:43 <bcoca> but any of those workflows should be ok, my only point is that 'aliases' are possible in 'non deprecation' cases
15:51:50 <bcoca> and we might want to treat those diff
15:52:36 <felixfontein> so stub for deprecation, symlink (which hopefully translates to redirect, depending on webserver I guess?) for aliases
15:52:59 <bcoca> webserver wont redirect, will just load target info under 'symlink name'
15:53:08 <bcoca> symlink == 'file alias'
15:53:21 <felixfontein> but then it's not a redirect?
15:53:25 <bcoca> nope
15:53:28 <acozine> bcoca: do we have a current example?
15:53:45 <felixfontein> now I'm really confused. I thought we wanted redirects for aliases.
15:54:26 <bcoca> i presented several options
15:54:29 <felixfontein> or is the same page as for the original name fine?
15:54:32 <bcoca> though symlnk for alias is simplest
15:55:10 <bcoca> felixfontein: yes, webserver just reads 'file x' if that file 'x' is symlink to 'y', contents of 'y' are presented
15:55:26 <felixfontein> (that's what I would expect from a webserver)
15:55:33 <bcoca> its a 'filesystem redirec't, not a http one
15:55:59 <bcoca> which i think is fine for aliases, but we might want stub file instead for deprecation
15:56:44 <gundalow> -1 to symlinks. That will confuse Google (etc) about what the primary page is
15:56:46 <felixfontein> if symlinks don't work we could also simply copy the .rst file. or does this screw up index generation? (I've never looked at how index generation works)
15:57:11 <bcoca> taht would create doulbe entries, you are better off with redirect or stub
15:57:26 <acozine> bcoca: are you suggesting that for aliases without deprecation, we do what we did for the osx_say to say change? https://github.com/ansible/ansible/commit/d8a2d64ec1b17e177f763c56287604d8661924f6
15:57:50 <bcoca> basically
15:57:55 <acozine> https://github.com/ansible/ansible/blob/d8a2d64ec1b17e177f763c56287604d8661924f6/lib/ansible/plugins/callback/osx_say.py
15:58:11 <bcoca> gundalow: consider that is probably ^ only case we have of actual 'alias' in our repo
15:58:29 * acozine looks at docsite to see how that functions
15:58:45 <bcoca> that probably generated 2 full pages with same content
15:59:17 <felixfontein> https://docs.ansible.com/ansible/devel/modules/osx_say_module.html is 404, https://docs.ansible.com/ansible/devel/modules/say_module.html works
15:59:30 <acozine> hmmmmmm, that's not doing what i thought it would do: https://docs.ansible.com/ansible/devel/plugins/callback/osx_say.html
15:59:30 <bcoca> i get content with both
15:59:47 <bcoca> felixfontein: callback plugins
15:59:53 <felixfontein> lol, sorry
16:00:13 <bcoca> acozine: cause rst is generated using 'file name' as plugin name
16:00:18 <felixfontein> both have content, but none mentions that the other is an alias
16:00:24 <bcoca> so it creates 2 diff pages with 'mostly same content'
16:00:29 <bcoca> yep, that is wrong
16:00:43 <felixfontein> (except in the notes)
16:00:45 <bcoca> ^ why aliases shoudl be handled as special case
16:01:14 <acozine> lord, it's worse than I thought
16:01:14 <bcoca> also, note ponints at module, not at callback plugin ... that is wrong
16:01:23 <acozine> yep, what bcoca said
16:01:26 <bcoca> why i cautioned about alias != deprecation
16:02:13 <bcoca> at least we now have example to go on
16:03:06 <acozine> yeah, it's nice to have a pair of use cases
16:03:17 <bcoca> 99% will be deprecation though
16:03:30 <bcoca> its always the 1%'s fault!
16:04:23 <felixfontein> so what should we do with aliases?
16:05:46 <acozine> my instinct says, let's fix deprecations
16:06:12 <acozine> if we can't fix aliases at the same time, we can make that a separate issue
16:06:18 <acozine> they are already broken
16:06:37 <bcoca> also, aliases have very little impact currently (all of 1) so seems good call imho
16:07:05 <felixfontein> ok. so create stub pages for deprecations, and a new issue for aliases?
16:07:07 <samccann> +1 for fixing deprecations
16:07:19 <acozine> +1 for felixfontein's plan
16:07:42 <felixfontein> I think the PR only handles deprecations at the moment anyway, because aliases aren't put into the aliases list
16:07:56 <felixfontein> (otherwise the osx_say / say callback plugin should have had them listed somehwere)
16:08:14 <acozine> ah, so maybe it's ready to go then
16:09:02 <acozine> I'll run a test on it, using the `github_hooks` and `digital_ocean` modules as examples
16:09:03 <felixfontein> I'll streamline it a bit so it won't start creating stubs for aliases if that's ever fixed
16:09:36 <acozine> felixfontein: sounds good, let me know when you're ready for a final test
16:09:44 <bcoca> aliases list should have all symlinks, unless someone added _prefix filter?
16:09:46 <acozine> see also https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_2.8.html#deprecated for where I got the deprecated modules to test
16:11:23 <acozine> bcoca: can you add those details to the issue about aliases, once we have one?
16:11:37 <bcoca> added to list
16:11:42 <acozine> thanks!
16:13:10 <felixfontein> acozine: I pushed the change, but local testing still takes some time...
16:13:16 <felixfontein> (sphinx is slow...)
16:13:45 <acozine> felixfontein: heh, yep - I'll keep an eye on the PR and run a non-local test when it's ready
16:13:54 <acozine> thanks for the work on this PR!
16:14:06 <bcoca> sorry for piling on can of worms ...
16:14:27 <acozine> bcoca: it's good to have someone who watches those corner cases
16:14:40 <acozine> but sometimes we can only put carpeting in the middle of the room
16:14:44 <acozine> today's one of those days, I think
16:14:47 <bcoca> i am a corner case (stats folk always find me in 'outlier' group)
16:14:50 <acozine> heh
16:14:58 <acozine> #topic custom 404 https://github.com/ansible/ansible/issues/51439
16:15:19 <acozine> I'd like to put some requirements on this issue, in the hopes that someone will pick it up
16:15:24 <acozine> right now it's a little sparse
16:16:20 <felixfontein> this sounds like it needs a lot of knowledge on how the different versions are actually stored on the webserver, especially if this is supposed to be a dynamic script and not a bunch of pregenerated HTML pages
16:16:47 <acozine> yeah, I think it might be too complicated as it stands
16:17:33 <acozine> a first-round fix might be a page with links to the index pages of all the currently-supported versions
16:17:49 <bcoca> normaly you want to udpate webserver config to point to specific http error response pages
16:18:30 <acozine> at the moment we don't have any error response pages, as far as I know
16:19:27 <felixfontein> indeed: https://docs.ansible.com/ansible/devel/modules/module/asdf.html
16:19:41 <acozine> felixfontein: exactly
16:20:07 <acozine> the least we can do is provide the left-nav and a pane that says "we couldn't find the page you were looking for"
16:20:20 <acozine> but give the user some way to move on from there
16:20:31 <acozine> it's a terrible user experience right now
16:20:57 <acozine> even if we do nothing about versions, we can do better than we're doing now
16:21:09 <felixfontein> pages generated by sphinx seem to use relative URLs by default, so using that to create a simple page for 404 doesn't really work (at least not without finding out how to tell sphinx to not make it use relative links)
16:21:10 <alongchamps> +1 on making it more useful - perhaps presenting the user with a search box
16:21:59 <bcoca> 404 are handled by webserver, so not really something you can redirect/point at
16:22:11 <bcoca> its normally webserver config that points to 'for 404 use this page'
16:22:13 <felixfontein> bcoca: you could create a page and tell webserver to serve that one on 404
16:22:27 <acozine> bcoca: but can't we point the webserver at a page like docs.ansible.com/ansible/404.html?
16:22:28 <bcoca> felixfontein: didnt i just text taht?
16:22:30 <alongchamps> yeah, I'm thinking a generic "we can't find what you're looking for" with a search for all versions
16:22:31 <felixfontein> but for that you need a page which looks good no matter under which URL it is shown
16:22:36 <acozine> I mean, if we had one?
16:22:37 <felixfontein> i.e. no relative URLs
16:22:55 <felixfontein> bcoca: I was typing while you wrote
16:23:00 <bcoca> 2 problems are 'custom header/footer' and 'breadcrumbs'
16:23:22 <bcoca> so error pages are normally devoid of both, use generic that works across versions/etc
16:23:37 <felixfontein> that's why generating the page with sphinx would be good. but only if we can force sphinx to generate absolute URLs in it
16:23:54 <acozine> https://pypi.org/project/sphinx-notfound-page/
16:24:16 <felixfontein> acozine: looks good!
16:24:46 <felixfontein> I'm surprised that sphinx can't do this out of the box, I would expect that this is a very commonly wanted feature
16:25:09 <acozine> me too
16:25:52 <felixfontein> meh. sphinx is still building.
16:26:37 * acozine hums the jeopardy theme song
16:27:19 <felixfontein> I guess when switching git branches, all files get touched and so it just wants to regenerate *everything*
16:27:49 <bcoca> sphinx cannot force web server, just build stuff and put in specifi location
16:28:06 <bcoca> i woudl NOT want sphinx to update webserver config ...
16:28:17 <felixfontein> bcoca: but it can prepare a page which can be used for 404 page
16:28:29 <felixfontein> that's usually the hard part, once you got that you only have to adjust webserver config once
16:28:45 <acozine> so, for the custom 404 thing, can we do this as a first round? add the sphinx-notfound-page extension, build a 404 page for `devel`, and test that we can reach it via the URL?
16:28:58 <acozine> once we have that, we can address the apache config side of things
16:29:12 <acozine> along with the other versions side of things
16:29:26 <bcoca> felixfontein: we keep saying same things in diff way
16:29:47 <felixfontein> yeah
16:29:57 <felixfontein> whee, sphinx finished!
16:30:03 <felixfontein> it only took 17 minutes
16:30:06 <acozine> heh
16:30:14 <acozine> okay, I have to run for my next meeting
16:30:28 <bcoca> https://docs.ansible.com/asldfkj  <= do we want /ansible 404 or full site one?
16:30:41 <bcoca> https://docs.ansible.com/ansible/asldfkj <= ansible specific
16:30:47 <acozine> bcoca: ansible-specific
16:31:01 <bcoca> so it needs to be a webserver config for /ansible subdir
16:31:04 <felixfontein> acozine: the link to the real module seems to be broken
16:31:07 <bcoca> we can coordinate that
16:31:48 <acozine> felixfontein: ugh
16:31:56 <felixfontein> acozine: I'm investigating
16:32:40 <acozine> I'll update the custom-404 issue with a list of requirements
16:32:47 <acozine> (the ones we know so far)
16:32:52 <bcoca> #1 must be cowsay based
16:33:02 <acozine> nope nope nope nope nope
16:33:03 <gundalow> 404 MUST be cowsay and
16:33:12 <gundalow> s/ and//
16:33:17 <bcoca> ______________________________________
16:33:19 <bcoca> / this is not the page you are looking \
16:33:20 <bcoca> \ for                                  /
16:33:22 <bcoca> --------------------------------------
16:33:23 <bcoca> \   ^__^
16:33:25 <bcoca> \  (oo)\_______
16:33:26 <bcoca> (__)\       )\/\
16:33:28 <bcoca> ||----w |
16:33:29 <bcoca> ||     ||
16:33:30 <samccann> 🐮
16:33:31 <bcoca> ^ and added jedi mind trick!
16:33:49 * acozine gives in to the enthusiasm for cows
16:33:59 <acozine> okay, we're over time for today
16:34:03 <bcoca> isnt' our 500 page also cowsay based?
16:34:05 <samccann> this is udderly rediculous
16:34:13 <acozine> oh, now this has to stop
16:34:18 <bcoca> samccann: let it go, its a mooooo point
16:34:27 <samccann> mooooooo
16:34:52 * bcoca cannot close pandora's box at this point, sorry acozine
16:34:59 <acozine> my vote is `neigh`
16:35:40 <acozine> bcoca: you didn't start it - I think cowsay was part of Ansible even before your time
16:36:01 <acozine> thanks everybody for a productive DaWGs meeting!
16:36:11 <bcoca> he, barely .. i probably worked the most on that 'feature'
16:36:14 <acozine> I'll update the 404 issue
16:36:28 <acozine> bcoca: oh, you DID start it, did you?
16:36:30 <felixfontein> acozine: PR is fixed, at least it works locally ;)
16:36:34 <bcoca> MPD did introduce it .. then was really suprised by how far i took it
16:36:40 <acozine> felixfontein: excellent!
16:36:53 <bcoca> acozine: run ansible with COW_SELECTION=random
16:37:01 <bcoca> ANSIBLE_COW_SELECTION
16:37:05 <acozine> okay, we're six minutes over, the official meeting part should end
16:37:12 <acozine> #endmeeting