Local dev configuration file #500
Conversation
| To see other available sessions, run `nox --list`. | ||
|
|
||
| > By default the `conf.py` file uses absolute urls for style sheets and other resources. | ||
| > If you do not specify the `dev.conf.py` file the resulting output uses resources hosted on `docs.ansible.com`, which means you cannot view local changes to `.sass` files and so on. |
There was a problem hiding this comment.
What's the motivation for using URL_TYPE = 'absolute' in conf.py? Why not use 'full_path' in conf.py?
There was a problem hiding this comment.
Thanks @felixfontein When I added the error pages plugin I ran into https://github.com/getnikola/plugins/blob/bf20b98ec7ade86950a32ba64133fda2160c948b/v7/errorpages/errorpages.py#L123
Then changed to absolute in conf.py after inspecting the source files.
We actually ran into an issue with the old ansible/docsite where relative paths were in places like the canonical url in pages on docs.ansible.com. I'm not sure if I can fully explain the issue but it boiled down to google treating pages as being "spammy" because of the relative urls. The fix was to switch to absolute urls. I can dig up the email thread if we need to go into it.
We didn't want to run into the same issue after switching to this repo. So it was kind of a happy coincidence that the error pages plugin revealed that nikola config parameter. It meant we could kill two birds with one stone: avoid relative paths in urls and generate 404 pages the way nikola intended.
I chose absolute because it looked like the best option based on my experience with that google issue, which I alluded to a little in this comment: #485 (comment)
Anyway, if full_path is just as good as absolute and also lets us preview local changes then I'm for it.
There was a problem hiding this comment.
I'm not sure if I can fully explain the issue but it boiled down to google treating pages as being "spammy" because of the relative urls.
Do you have further information on this? This would also be important for Sphinx generated documentation, as Sphinx uses relative links for almost everything.
Anyway, if
full_pathis just as good asabsoluteand also lets us preview local changes then I'm for it.
It's much better, since a) it's shorter, and b) it works if the host changes - like when serving docs locally (especially without internet connection), or when looking at RTD PR previews.
Even better would be relative URLs, since they even work in subdirectories (like when opening file:// URIs in your browser with the built documentation). The only exception are 404 pages (or other error pages), that have to use full_path or absolute (and for the above reasons, preferably full_path).
3 participants
Add a local dev configuration file that does not use absolute urls. @x1101 FYI