Skip to content

doc: fix paths on 404 pages - #1479

Open
elijahgreenstein wants to merge 2 commits into
canonical:mainfrom
elijahgreenstein:404-urls
Open

doc: fix paths on 404 pages#1479
elijahgreenstein wants to merge 2 commits into
canonical:mainfrom
elijahgreenstein:404-urls

Conversation

@elijahgreenstein

Copy link
Copy Markdown
Contributor

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.

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>
@elijahgreenstein

Copy link
Copy Markdown
Contributor Author

Note that the 404 page will not render correctly in the RTD test build (this can be viewed by appending 404 to the end of the RTD build URL), since the URLs are all absolute paths that begin with /microcloud/docs/{version}/. This pattern works in the actual documentation at https://canonical.com/microcloud/docs/, but not in the RTD test build. However, I have checked the page source of the 404 page, and the updated paths all look correct to me, and align with other paths on the 404 page that are working correctly in the live documentation. For example, the navigation menu link to the tutorials has the path href="/microcloud/docs/1479/tutorial/", where 1479 is the "version" of the RTD test build. Likewise, the LXD top navigation menu path is now href="/microcloud/docs/1479/lxd/". The tutorial link on the active 404 page works; hence, I expect this LXD link to work as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant