notfound.extension
==================

.. py:module:: notfound.extension


Exceptions
----------

.. autoapisummary::

   notfound.extension.BaseURIError


Classes
-------

.. autoapisummary::

   notfound.extension.OrphanMetadataCollector


Functions
---------

.. autoapisummary::

   notfound.extension.html_collect_pages
   notfound.extension.finalize_media
   notfound.extension.doctree_resolved
   notfound.extension.validate_configs
   notfound.extension.setup


Module Contents
---------------

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

   Bases: :py:obj:`sphinx.errors.ExtensionError`


   Exception for malformed base URI.


.. py:function:: 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.

   :param app: Sphinx Application
   :type app: sphinx.application.Sphinx


.. py:function:: 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``)

   :param app: Sphinx Application
   :type app: sphinx.application.Sphinx

   :param pagename: name of the page being rendered
   :type pagename: str

   :param templatename: template used to render the page
   :type templatename: str

   :param context: context used to render the page
   :type context: dict

   :param doctree: doctree of the page being rendered
   :type doctree: docutils.nodes.document


.. py:function:: 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.

   :param app: Sphinx Application
   :type app: sphinx.application.Sphinx
   :param doctree: doctree representing the document
   :type doctree: docutils.nodes.document
   :param docname: name of the document
   :type docname: str


.. py:class:: OrphanMetadataCollector

   Bases: :py:obj:`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.


   .. py:method:: clear_doc(app, env, docname)

      Remove specified data of a document.

      This method is called on the removal of the document.



   .. py:method:: process_doc(app, doctree)

      Process a document and gather specific data from it.

      This method is called after the document is read.



   .. py:method:: 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.



.. py:function:: validate_configs(app, *args, **kwargs)

   Validate configs.

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


.. py:function:: setup(app)