From d0eb7e4624b13718efe23a71319a864f474c9a2e Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 9 Jan 2024 14:52:37 -0600 Subject: [PATCH] maybe fix missing sidebar? (#1632) * maybe fix missing sidebar? * simplify * purge internal defaults & use theme config setting * formatting * refactor and simplify toctree code --- .../components/sidebar-nav-bs.html | 8 +- .../theme/pydata_sphinx_theme/layout.html | 2 +- src/pydata_sphinx_theme/toctree.py | 126 +++++++++--------- 3 files changed, 66 insertions(+), 70 deletions(-) diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-nav-bs.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-nav-bs.html index 38763d797..fd1fd9dfe 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-nav-bs.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-nav-bs.html @@ -5,10 +5,10 @@
{{- generate_toctree_html( "sidebar", - show_nav_level=theme_show_nav_level|int, - maxdepth=theme_navigation_depth|int, - collapse=theme_collapse_navigation|tobool, - includehidden=True, + show_nav_level=theme_show_nav_level | int, + maxdepth=theme_navigation_depth | int, + collapse=theme_collapse_navigation | tobool, + includehidden=theme_sidebar_includehidden | tobool, titles_only=True ) -}} diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html index 324b39884..c9e97c080 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html @@ -80,7 +80,7 @@
{# Primary sidebar #} {# If we have no sidebar TOC, pop the TOC component from the sidebar list #} - {% if get_sidebar_toctree_length(show_nav_level=theme_show_nav_level|int) == 0 %} + {% if missing_sidebar_toctree(includehidden=theme_sidebar_includehidden) %} {% set sidebars = sidebars | reject("in", "sidebar-nav-bs.html") | list %} {% endif %}
diff --git a/src/pydata_sphinx_theme/toctree.py b/src/pydata_sphinx_theme/toctree.py index f8c46d924..03bbc46ea 100644 --- a/src/pydata_sphinx_theme/toctree.py +++ b/src/pydata_sphinx_theme/toctree.py @@ -9,8 +9,7 @@ from bs4 import BeautifulSoup from docutils import nodes from docutils.nodes import Node -from sphinx import addnodes -from sphinx.addnodes import toctree as toctree_node +from sphinx.addnodes import toctree as TocTreeNodeClass from sphinx.application import Sphinx from sphinx.environment.adapters.toctree import TocTree from sphinx.locale import _ @@ -32,15 +31,8 @@ def add_inline_math(node: Node) -> str: ) -def get_unrendered_local_toctree( - app: Sphinx, pagename: str, startdepth: int, collapse: bool = True, **kwargs -): - """.""" - if "includehidden" not in kwargs: - kwargs["includehidden"] = False - if kwargs.get("maxdepth") == "": - kwargs.pop("maxdepth") - +def _get_ancestor_section(app: Sphinx, pagename: str, startdepth: int) -> str: + """Get the TocTree node `startdepth` levels below the root that dominates `pagename`.""" toctree = TocTree(app.env) if sphinx.version_info[:2] >= (7, 2): from sphinx.environment.adapters.toctree import _get_toctree_ancestors @@ -49,16 +41,30 @@ def get_unrendered_local_toctree( else: ancestors = toctree.get_toctree_ancestors(pagename) try: - indexname = ancestors[-startdepth] + return ancestors[-startdepth] # will be a pagename (string)? except IndexError: # eg for index.rst, but also special pages such as genindex, py-modindex, search # those pages don't have a "current" element in the toctree, so we can # directly return an empty string instead of using the default sphinx # toctree.get_toctree_for(pagename, app.builder, collapse, **kwargs) - return "" + return None - return get_local_toctree_for( - toctree, indexname, pagename, app.builder, collapse, **kwargs + +def get_unrendered_local_toctree(app: Sphinx, pagename: str, startdepth: int, **kwargs): + """Get the "local" (starting at `startdepth`) TocTree containing `pagename`. + + This is similar to `context["toctree"](**kwargs)` in sphinx templating, + but using the startdepth-local instead of global TOC tree. + """ + kwargs.setdefault("collapse", True) + if kwargs.get("maxdepth") == "": + kwargs.pop("maxdepth") + toctree = TocTree(app.env) + indexname = _get_ancestor_section(app=app, pagename=pagename, startdepth=startdepth) + if indexname is None: + return None + return get_local_toctree_for_doc( + toctree, indexname, pagename, app.builder, **kwargs ) @@ -67,11 +73,18 @@ def add_toctree_functions( ) -> None: """Add functions so Jinja templates can add toctree objects.""" - def get_sidebar_toctree_length( - startdepth: int = 1, show_nav_level: int = 1, **kwargs - ): - toctree = get_unrendered_local_toctree(app, pagename, startdepth) - return 0 if toctree is None else len(toctree) + def missing_sidebar_toctree(startdepth: int = 1, **kwargs): + """Check if there's a sidebar TocTree that needs to be rendered. + + Parameters: + startdepth : The level of the TocTree at which to start. 0 includes the + entire TocTree for the site; 1 (default) gets the TocTree for the current + top-level section. + + kwargs: passed to the Sphinx `toctree` template function. + """ + toctree = get_unrendered_local_toctree(app, pagename, startdepth, **kwargs) + return toctree is None @cache def get_or_create_id_generator(base_id: str) -> Iterator[str]: @@ -120,8 +133,8 @@ def generate_header_nav_before_dropdown(n_links_before_dropdown): # Iterate through each toctree node in the root document # Grab the toctree pages and find the relative link + title. links_html = [] - # TODO: use `root.findall(toctree_node)` once docutils min version >=0.18.1 - for toc in traverse_or_findall(root, toctree_node): + # TODO: use `root.findall(TocTreeNodeClass)` once docutils min version >=0.18.1 + for toc in traverse_or_findall(root, TocTreeNodeClass): for title, page in toc.attributes["entries"]: # if the page is using "self" use the correct link page = toc.attributes["parent"] if page == "self" else page @@ -255,12 +268,15 @@ def generate_toctree_html( HTML string (if kind == "sidebar") OR BeautifulSoup object (if kind == "raw") """ if startdepth == 0: - toc_sphinx = context["toctree"](**kwargs) + html_toctree = context["toctree"](**kwargs) else: # select the "active" subset of the navigation tree for the sidebar - toc_sphinx = index_toctree(app, pagename, startdepth, **kwargs) + toctree_element = get_unrendered_local_toctree( + app, pagename, startdepth, **kwargs + ) + html_toctree = app.builder.render_partial(toctree_element)["fragment"] - soup = BeautifulSoup(toc_sphinx, "html.parser") + soup = BeautifulSoup(html_toctree, "html.parser") # pair "current" with "active" since that's what we use w/ bootstrap for li in soup("li", {"class": "current"}): @@ -378,7 +394,7 @@ def navbar_align_class() -> List[str]: context["unique_html_id"] = unique_html_id context["generate_header_nav_html"] = generate_header_nav_html - context["get_sidebar_toctree_length"] = get_sidebar_toctree_length + context["missing_sidebar_toctree"] = missing_sidebar_toctree context["generate_toctree_html"] = generate_toctree_html context["generate_toc_html"] = generate_toc_html context["navbar_align_class"] = navbar_align_class @@ -443,56 +459,36 @@ def add_collapse_checkboxes(soup: BeautifulSoup) -> None: element.insert(1, checkbox) -def get_local_toctree_for( - self: TocTree, indexname: str, docname: str, builder, collapse: bool, **kwargs +def get_local_toctree_for_doc( + toctree: TocTree, indexname: str, pagename: str, builder, collapse: bool, **kwargs ) -> List[BeautifulSoup]: - """Return the "local" TOC nodetree (relative to `indexname`).""" - # this is a copy of `TocTree.get_toctree_for`, but where the sphinx version - # always uses the "root" doctree: - # doctree = self.env.get_doctree(self.env.config.root_doc) - # we here use the `indexname` additional argument to be able to use a subset - # of the doctree (e.g. starting at a second level for the sidebar): - # doctree = app.env.tocs[indexname].deepcopy() + """Get the "local" TocTree containing `pagename` rooted at `indexname`. - doctree = self.env.tocs[indexname].deepcopy() + The Sphinx equivalent is TocTree.get_toctree_for(), which always uses the "root" + or "global" TocTree: + + doctree = self.env.get_doctree(self.env.config.root_doc) + + Whereas here we return a subset of the global toctree, rooted at `indexname` + (e.g. starting at a second level for the sidebar). + """ + partial_doctree = toctree.env.tocs[indexname].deepcopy() toctrees = [] - if "includehidden" not in kwargs: - kwargs["includehidden"] = True if "maxdepth" not in kwargs or not kwargs["maxdepth"]: kwargs["maxdepth"] = 0 - else: - kwargs["maxdepth"] = int(kwargs["maxdepth"]) + kwargs["maxdepth"] = int(kwargs["maxdepth"]) kwargs["collapse"] = collapse - # TODO: use `doctree.findall(addnodes.toctree)` once docutils min version >=0.18.1 - for toctreenode in traverse_or_findall(doctree, addnodes.toctree): - toctree = self.resolve(docname, builder, toctreenode, prune=True, **kwargs) - if toctree: - toctrees.append(toctree) + # TODO: use `doctree.findall(TocTreeNodeClass)` once docutils min version >=0.18.1 + for _node in traverse_or_findall(partial_doctree, TocTreeNodeClass): + # defaults for resolve: prune=True, maxdepth=0, titles_only=False, collapse=False, includehidden=False + _toctree = toctree.resolve(pagename, builder, _node, **kwargs) + if _toctree: + toctrees.append(_toctree) if not toctrees: return None result = toctrees[0] for toctree in toctrees[1:]: result.extend(toctree.children) return result - - -def index_toctree( - app: Sphinx, pagename: str, startdepth: int, collapse: bool = True, **kwargs -): - """Returns the "local" (starting at `startdepth`) TOC tree containing the current page, rendered as HTML bullet lists. - - This is the equivalent of `context["toctree"](**kwargs)` in sphinx - templating, but using the startdepth-local instead of global TOC tree. - """ - # this is a variant of the function stored in `context["toctree"]`, which is - # defined as `lambda **kwargs: self._get_local_toctree(pagename, **kwargs)` - # with `self` being the HMTLBuilder and the `_get_local_toctree` basically - # returning: - # return self.render_partial(TocTree(self.env).get_toctree_for( - # pagename, self, collapse, **kwargs))['fragment'] - toctree_element = get_unrendered_local_toctree( - app, pagename, startdepth, collapse, **kwargs - ) - return app.builder.render_partial(toctree_element)["fragment"]