1421241 - sphinx-autobuild isn't documented and doesn't detect changes correctly

Status: RESOLVED FIXED

(Tree Management :: Treeherder, enhancement, P2)

Description

[Ed Morley [:emorley]]

sphinx-autobuild (which provides an auto-reloading web server to make previewing docs changes easier) support was added in:
https://github.com/mozilla/treeherder/pull/1545

However it's not documented here:
https://treeherder.readthedocs.io/common_tasks.html#building-the-docs-locally

And also it doesn't detect changes correctly in the Vagrant environment (it needs to be using the `--poll` option).

Comment 1

[Treeherder GitHub Bugbot]

Commits pushed to master at https://github.com/mozilla/treeherder

https://github.com/mozilla/treeherder/commit/b7e6db1f94660ecf553763ec88dc817873ef1e9c
Bug 1421241 - Docs: Remove unused Makefile targets

We don't use any of the other build modes:
http://www.sphinx-doc.org/en/stable/builders.html#builders

https://github.com/mozilla/treeherder/commit/607007d7e8d7771902598fbcc0dd1a792998c7db
Bug 1421241 - Docs: Reduce nesting of build output directory

Since there is only ever one build type, so the nested directory is
unnecessary and makes it more annoying to find the built assets.

https://github.com/mozilla/treeherder/commit/194e3e3be53eccdbb7722a0d67009606d20acb64
Bug 1421241 - Docs: Improve livehtml mode and recommend it

* 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.

https://github.com/mozilla/treeherder/commit/86e140236974a2911619e1f3e426c3e110eb78c9
Bug 1421241 - Docs: Improve error shown when Sphinx not installed

https://github.com/mozilla/treeherder/commit/331a39bff25b65f02aace532d53710aa57ba2c3c
Bug 1421241 - Docs: Add livehtml to the Makefile help text