doc: fix paths on 404 pages - #1479
Conversation
With the exception of the MicroCloud logo, the relative paths are not
resolving correctly for href links and logo static files in the top
navigation menu on 404 pages, nor are the resolving correctly for two
"brand" href links (one in the sidebar and the other at the top of the
page). Issues include:
- MicroCloud links in the top navigation menu, at the top of the page,
and in the sidebar resolve to "#", which means that these links cannot
be used to navigate back to the docs homepage.
- LXD, MicroCeph, and MicroOVN href links and static file paths in the
to navigation menu resolve to the product (e.g. `lxd/`) or the tag
path (e.g. `lxd/_static/lxd_tag.png`), which appends those paths to
the end of the URL that lands on a 404 page (e.g. on
`canonical.com/microcloud/docs/latest/bad-url/`, the LXD link goes to
`canonical.com/microcloud/docs/latest/bad-url/lxd/`. As a result, the
logos are not loading and the links cannot be used to navigate to the
LXD, etc. docs subsets.
To resolve this issue, this commit:
- Adds `nav404_prefix` to `html_context` and sets it to the path portion
of `html_baseurl`. This makes the base path available in HTML
templates.
- Updates the MicroCloud header template with if-else statements, to use
`nav404_prefix` on 404 pages. Note that only the MicroCloud header
(`microcloud.html`) needed to be updated, since 404 pages across the
integrated docs use the MicroCloud template (rather than to the LXD,
MicroCeph, and MicroOVN subsets). This hard-codes the correct path
into the 404 page generated by Sphinx.
- Updates the Makefile to replace `"#"` in the "brand" href links with
the correct `/microcloud/docs/{version}` path.
Note that the Makefile update depends on the current docs URL pattern
(`https://canonical.com/microcloud/docs/{version}/` and will require a
manual update if the docs move to a new URL pattern.
Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
This commits adds checks to the Makefile to ensure that expected patterns are found in the built 404 pages before replacing href links. Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
35f4137 to
3b9e77b
Compare
|
Note that the 404 page will not render correctly in the RTD test build (this can be viewed by appending |
With the exception of the MicroCloud logo, the relative paths are not resolving correctly for href links and logo static files in the top navigation menu on 404 pages, nor are the resolving correctly for two "brand" href links (one in the sidebar and the other at the top of the page). Issues include:
lxd/) or the tag path (e.g.lxd/_static/lxd_tag.png), which appends those paths to the end of the URL that lands on a 404 page (e.g. oncanonical.com/microcloud/docs/latest/bad-url/, the LXD link goes tocanonical.com/microcloud/docs/latest/bad-url/lxd/. As a result, the logos are not loading and the links cannot be used to navigate to the LXD, etc. docs subsets.To resolve this issue, this commit:
nav404_prefixtohtml_contextand sets it to the path portion ofhtml_baseurl. This makes the base path available in HTML templates.nav404_prefixon 404 pages. Note that only the MicroCloud header (microcloud.html) needed to be updated, since 404 pages across the integrated docs use the MicroCloud template (rather than to the LXD, MicroCeph, and MicroOVN subsets). This hard-codes the correct path into the 404 page generated by Sphinx."#"in the "brand" href links with the correct/microcloud/docs/{version}path.Note that the Makefile update depends on the current docs URL pattern (
https://canonical.com/microcloud/docs/{version}/and will require a manual update if the docs move to a new URL pattern.