pydata_sphinx_theme.toctree#

Methods to build the toctree used in the html pages.

Classes#

LinkInfo

Dataclass to generate toctree data.

Functions#

_get_ancestor_pagename(app, pagename, startdepth)

Get the name of pagename's ancestor that is rooted startdepth levels below the

_move_current_markers(soup, *, old_href, new_href, ...)

Move the "current page" markers in a rendered sidebar toctree.

_patch_cached_sidebar(app, cache_key, pagename, ...)

Return this page's sidebar HTML by patching a cached sibling page's soup.

_set_current_chain(anchor, *, current, show_nav_level)

Add or remove current/active/open markers on an entry's ancestor chain.

_sidebar_cache(app)

Return the per-build sidebar toctree cache, stored on the Sphinx app.

_sidebar_cache_key(kind, ancestorname, page_uri, ...)

Return the sidebar toctree cache key for this page, or None if uncacheable.

add_collapse_checkboxes(soup)

Add checkboxes to collapse children in a toctree.

add_inline_math(node)

Render a node with HTML tags that activate MathJax processing.

add_toctree_functions(app, pagename, templatename, ...)

Add functions so Jinja templates can add toctree objects.

get_nonroot_toctree(app, pagename, ancestorname, ...)

Get the partial TocTree (rooted at ancestorname) that dominates pagename.

Module Contents#

class pydata_sphinx_theme.toctree.LinkInfo[source]#

Dataclass to generate toctree data.

href: str#
is_current: bool#
is_current_page: bool = False#
is_external: bool#
title: str#
pydata_sphinx_theme.toctree._get_ancestor_pagename(app, pagename, startdepth)[source]#

Get the name of pagename’s ancestor that is rooted startdepth levels below the global root.

Parameters:
Return type:

str

pydata_sphinx_theme.toctree._move_current_markers(soup, *, old_href, new_href, show_nav_level)[source]#

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 <details> 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.

Parameters:

  • soup (bs4.BeautifulSoup)

  • old_href (str)

  • new_href (str)

  • show_nav_level (int)

Return type:

bool

pydata_sphinx_theme.toctree._patch_cached_sidebar(app, cache_key, pagename, show_nav_level)[source]#

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.

Parameters:
Return type:

str | None

pydata_sphinx_theme.toctree._set_current_chain(anchor, *, current, show_nav_level)[source]#

Add or remove current/active/open markers on an entry’s ancestor chain.

Parameters:

  • current (bool)

  • show_nav_level (int)

Return type:

None

pydata_sphinx_theme.toctree._sidebar_cache(app)[source]#

Return the per-build sidebar toctree cache, stored on the Sphinx app.

Parameters:

app (sphinx.application.Sphinx)

Return type:

dict

pydata_sphinx_theme.toctree._sidebar_cache_key(kind, ancestorname, page_uri, show_nav_level, kwargs)[source]#

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 <details>) 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.

Parameters:

  • kind (str)

  • ancestorname (str | None)

  • page_uri (str)

  • show_nav_level (int)

  • kwargs (dict)

Return type:

tuple | None

pydata_sphinx_theme.toctree.add_collapse_checkboxes(soup)[source]#

Add checkboxes to collapse children in a toctree.

Parameters:

soup (bs4.BeautifulSoup)

Return type:

None

pydata_sphinx_theme.toctree.add_inline_math(node)[source]#

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: sphinx-doc/sphinx

Parameters:

node (docutils.nodes.Node)

Return type:

str

pydata_sphinx_theme.toctree.add_toctree_functions(app, pagename, templatename, context, doctree)[source]#

Add functions so Jinja templates can add toctree objects.

Parameters:
Return type:

None

pydata_sphinx_theme.toctree.get_nonroot_toctree(app, pagename, ancestorname, toctree, **kwargs)[source]#

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)).

Parameters: