pydata_sphinx_theme.toctree =========================== .. py:module:: pydata_sphinx_theme.toctree .. autoapi-nested-parse:: Methods to build the toctree used in the html pages. .. !! processed by numpydoc !! Classes ------- .. autoapisummary:: pydata_sphinx_theme.toctree.LinkInfo Functions --------- .. autoapisummary:: pydata_sphinx_theme.toctree._get_ancestor_pagename pydata_sphinx_theme.toctree._move_current_markers pydata_sphinx_theme.toctree._patch_cached_sidebar pydata_sphinx_theme.toctree._set_current_chain pydata_sphinx_theme.toctree._sidebar_cache pydata_sphinx_theme.toctree._sidebar_cache_key pydata_sphinx_theme.toctree.add_collapse_checkboxes pydata_sphinx_theme.toctree.add_inline_math pydata_sphinx_theme.toctree.add_toctree_functions pydata_sphinx_theme.toctree.get_nonroot_toctree Module Contents --------------- .. py:class:: LinkInfo Dataclass to generate toctree data. .. !! processed by numpydoc !! .. py:attribute:: href :type: str .. py:attribute:: is_current :type: bool .. py:attribute:: is_current_page :type: bool :value: False .. py:attribute:: is_external :type: bool .. py:attribute:: title :type: str .. py:function:: _get_ancestor_pagename(app, pagename, startdepth) Get the name of `pagename`'s ancestor that is rooted `startdepth` levels below the global root. .. !! processed by numpydoc !! .. py:function:: _move_current_markers(soup, *, old_href, new_href, show_nav_level) Move the "current page" markers in a rendered sidebar toctree. ``soup`` was rendered for another page in the same directory, whose entry (as seen from the page at ``new_href``) is at ``old_href``. Relocate the ``current``/``active`` classes and the ``open`` state of ``
`` disclosure widgets from that page's entry chain to the entry for the page at ``new_href``. Return ``False`` (leaving ``soup`` unmodified) if no entry for ``new_href`` exists. .. !! processed by numpydoc !! .. py:function:: _patch_cached_sidebar(app, cache_key, pagename, show_nav_level) Return this page's sidebar HTML by patching a cached sibling page's soup. Return None (and leave the cache unmodified) if no soup is cached under `cache_key` yet, or if the cached soup contains no entry for this page (e.g., it was pruned by `maxdepth`) -- the caller then builds the sidebar the slow way. .. !! processed by numpydoc !! .. py:function:: _set_current_chain(anchor, *, current, show_nav_level) Add or remove current/active/open markers on an entry's ancestor chain. .. !! processed by numpydoc !! .. py:function:: _sidebar_cache(app) Return the per-build sidebar toctree cache, stored on the Sphinx app. .. !! processed by numpydoc !! .. py:function:: _sidebar_cache_key(kind, ancestorname, page_uri, show_nav_level, kwargs) Return the sidebar toctree cache key for this page, or None if uncacheable. When `collapse=False` (i.e., theme option `collapse_navigation=False`, which is our default; note that Sphinx's `_get_local_toctree` defaults to `collapse=True`), the resolved toctree has the same structure for every page under the same ancestor -- only the "current" markers (`current`/`active` classes and open `
`) and the relative link targets differ. So the finished soup can be shared by all pages written to the same output directory (same relative link targets) below the same ancestor, provided the "current" markers are moved to each page's own toctree entry (_patch_cached_sidebar). `page_uri` is this page's output URI (`builder.get_target_uri()`), not its docname: builders whose page URIs are directories rather than files (e.g. "dirhtml") give every page its own output directory, so no two pages can share a sidebar and nothing is cached for them. .. !! processed by numpydoc !! .. py:function:: add_collapse_checkboxes(soup) Add checkboxes to collapse children in a toctree. .. !! processed by numpydoc !! .. py:function:: add_inline_math(node) Render a node with HTML tags that activate MathJax processing. This is meant for use with rendering section titles with math in them, because math outputs are ignored by pydata-sphinx-theme's header. related to the behaviour of a normal math node from: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/mathjax.py#L28 .. !! processed by numpydoc !! .. py:function:: add_toctree_functions(app, pagename, templatename, context, doctree) Add functions so Jinja templates can add toctree objects. .. !! processed by numpydoc !! .. py:function:: get_nonroot_toctree(app, pagename, ancestorname, toctree, **kwargs) Get the partial TocTree (rooted at `ancestorname`) that dominates `pagename`. Parameters: app : Sphinx app. pagename : Name of the current page (as Sphinx knows it; i.e., its relative path from the documentation root). ancestorname : Name of a page that dominates `pagename` and that will serve as the root of the TocTree fragment. toctree : A Sphinx TocTree object. Since this is always needed when finding the ancestorname (see _get_ancestor_pagename), it's more efficient to pass it here to re-use it. kwargs : passed to the Sphinx `toctree` template function. This is similar to `context["toctree"](**kwargs)` (AKA `toctree(**kwargs)` within a Jinja template), or `TocTree.get_toctree_for()`, which always uses the "root" doctree (i.e., `doctree = self.env.get_doctree(self.env.config.root_doc)`). .. !! processed by numpydoc !!