Various docs improvements #2996
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The build previously contained warnings like: ``` docs/rest_api.rst:144: WARNING: Title underline too short. docs/admin.rst:18: WARNING: Could not lex literal_block as "sql". Highlighting skipped. WARNING: html_static_path entry u'.../docs/_static' does not exist ```
So that the build fails if there are any warnings: http://www.sphinx-doc.org/en/stable/invocation.html#invocation-of-sphinx-build
As found by running `make -C docs linkcheck`.
We don't use any of the other build modes: http://www.sphinx-doc.org/en/stable/builders.html#builders
Since there is only ever one build type, so the nested directory is unnecessary and makes it more annoying to find the built assets.
* Removes the unnecessary initial `make html`, since sphinx-autobuild performs the initial build itself. * Enables `--poll` watch mode, since file change detection otherwise doesn't work in Vagrant. * Updates the docs to recommend the livereload web server over the one-off build when working on docs locally.
Since otherwise the page titles contain the word 'prototype': `- Treeherder prototype documentation`
This means less to both install and run at build time, hopefully speeding up the build and reducing the chance of races/locking issues.
Most of the existing config (generated by `sphinx-quickstart`) was either commented out, identical to the defaults or else for build modes we do not use - and only end up making the config hard to read.
camd
approved these changes
Nov 28, 2017
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Amongst other things this addresses:
See individual commits for more details.