notfound.extension

Exceptions

BaseURIError

Exception for malformed base URI.

Classes

OrphanMetadataCollector

Force the 404 page to be orphan.

Functions

html_collect_pages(app)

Create a 404.html page.

finalize_media(app, pagename, templatename, context, ...)

Point media files at our media server.

doctree_resolved(app, doctree, docname)

Generate and override URLs for .. image:: Sphinx directive.

validate_configs(app, *args, **kwargs)

Validate configs.

setup(app)

Module Contents

exception notfound.extension.BaseURIError(message: str, orig_exc: Exception | None = None, modname: str | None = None)

Bases: sphinx.errors.ExtensionError

Exception for malformed base URI.

notfound.extension.html_collect_pages(app)

Create a 404.html page.

Uses notfound_template as a template to be rendered with notfound_context for its context. The resulting file generated is notfound_pagename.html.

If the user already defined a page with pagename title notfound_pagename, we don’t generate this page.

Parameters:

app (sphinx.application.Sphinx) – Sphinx Application

notfound.extension.finalize_media(app, pagename, templatename, context, doctree)

Point media files at our media server.

Generate absolute URLs for resources (js, images, css, etc) to point to the right URL. For example, if a URL in the page is _static/js/custom.js it will be replaced by <notfound_urls_prefix>/_static/js/custom.js.

Also, all the links from the sidebar (toctree) are replaced with their absolute version. For example, ../section/pagename.html will be replaced by /section/pagename.html.

It handles a special case for Read the Docs and URLs starting with /_/. These URLs have a special meaning under Read the Docs and don’t have to be changed. (e.g. /_/static/javascript/readthedocs-doc-embed.js)

Parameters:

  • app (sphinx.application.Sphinx) – Sphinx Application

  • pagename (str) – name of the page being rendered

  • templatename (str) – template used to render the page

  • context (dict) – context used to render the page

  • doctree (docutils.nodes.document) – doctree of the page being rendered

notfound.extension.doctree_resolved(app, doctree, docname)

Generate and override URLs for .. image:: Sphinx directive.

When .. image:: is used in the 404.rst file, this function will override the URLs to point to the right place.

Parameters:

  • app (sphinx.application.Sphinx) – Sphinx Application

  • doctree (docutils.nodes.document) – doctree representing the document

  • docname (str) – name of the document

class notfound.extension.OrphanMetadataCollector

Bases: sphinx.environment.collectors.EnvironmentCollector

Force the 404 page to be orphan.

This way we remove the WARNING that Sphinx raises saying the page is not included in any toctree.

This collector has the same effect than :orphan: at the top of the page.

clear_doc(app, env, docname)

Remove specified data of a document.

This method is called on the removal of the document.

process_doc(app, doctree)

Process a document and gather specific data from it.

This method is called after the document is read.

merge_other(app, env, docnames, other)

Merge in specified data regarding docnames from a different BuildEnvironment object which coming from a subprocess in parallel builds.

notfound.extension.validate_configs(app, *args, **kwargs)

Validate configs.

Shows a warning if one of the configs is not valid.

notfound.extension.setup(app)