Since the deploy guide moved to a separate directory structure, relative
links throughout the docs have been pointing to nothing. This change
applies some logic to figure out the correct format for URLs based on
the current branch and the deploy guide/dev docs conventions.
The actual link generation is done via the sphinx.ext.extlinks
extension, which allows for defining custom link generation roles. This
achieves the desired behavior in terms of dynamic link construction, but
does alter the standard linking conventions.
Another side effect is that docs generate this way will always point
to the live URLs, not to HTML generated for a gate job. It may be
worthwhile using relative links within the deploy guide/developer docs
and only using these automatic external ones for cross-references.
Usage for dev docs looks like this:
:dev_docs:`Link title text <last-part-of-url.html>`
And for the deploy guide:
:deploy_guide:`Link title text <last-part-of-url.html>`
Some examples inline have been provided, to demonstrate how these fit in
different contexts.
Some small code style fixes are also included.
Change-Id: I4d065f1f2d7c1372f3f829ab9e5297d5028f2ee6
a1a25002ba