From d359930d014a08d1768f5a013182aec0ca9f44e3 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Fri, 5 Jan 2024 17:31:59 -0600 Subject: [PATCH 1/5] maybe fix missing sidebar? --- src/pydata_sphinx_theme/toctree.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/pydata_sphinx_theme/toctree.py b/src/pydata_sphinx_theme/toctree.py index f8c46d924..300dfe627 100644 --- a/src/pydata_sphinx_theme/toctree.py +++ b/src/pydata_sphinx_theme/toctree.py @@ -35,9 +35,12 @@ 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 + """Get the "local" (starting at `startdepth`) TOC tree containing the current page. + + This is similar to `context["toctree"](**kwargs)` in sphinx templating, + but using the startdepth-local instead of global TOC tree. + """ + kwargs.setdefault("includehidden", True) if kwargs.get("maxdepth") == "": kwargs.pop("maxdepth") @@ -457,12 +460,10 @@ def get_local_toctree_for( doctree = self.env.tocs[indexname].deepcopy() toctrees = [] - if "includehidden" not in kwargs: - kwargs["includehidden"] = True + kwargs.setdefault("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 From bd8f789b5926a8a5ac1b66bc1ef00867ddef069b Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 8 Jan 2024 11:24:52 -0600 Subject: [PATCH 2/5] simplify --- .../theme/pydata_sphinx_theme/layout.html | 2 +- src/pydata_sphinx_theme/toctree.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) 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 13ea08afd..48c8532db 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html @@ -82,7 +82,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 check_for_sidebar_toctree(show_nav_level=theme_show_nav_level|int) %} {% 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 300dfe627..219a0ac73 100644 --- a/src/pydata_sphinx_theme/toctree.py +++ b/src/pydata_sphinx_theme/toctree.py @@ -70,11 +70,11 @@ def add_toctree_functions( ) -> None: """Add functions so Jinja templates can add toctree objects.""" - def get_sidebar_toctree_length( + def check_for_sidebar_toctree( 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) + return toctree is not None @cache def get_or_create_id_generator(base_id: str) -> Iterator[str]: @@ -381,7 +381,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["check_for_sidebar_toctree"] = check_for_sidebar_toctree context["generate_toctree_html"] = generate_toctree_html context["generate_toc_html"] = generate_toc_html context["navbar_align_class"] = navbar_align_class From 57728c9519f8fc51066e5097fe47ae65b3058fb2 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 8 Jan 2024 11:27:48 -0600 Subject: [PATCH 3/5] purge internal defaults & use theme config setting --- .../pydata_sphinx_theme/components/sidebar-nav-bs.html | 2 +- .../theme/pydata_sphinx_theme/layout.html | 6 +++++- src/pydata_sphinx_theme/toctree.py | 2 -- 3 files changed, 6 insertions(+), 4 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..2d52b5378 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 @@ -8,7 +8,7 @@ show_nav_level=theme_show_nav_level|int, maxdepth=theme_navigation_depth|int, collapse=theme_collapse_navigation|tobool, - includehidden=True, + 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 48c8532db..cb195230c 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html @@ -82,7 +82,11 @@
{# Primary sidebar #} {# If we have no sidebar TOC, pop the TOC component from the sidebar list #} - {% if check_for_sidebar_toctree(show_nav_level=theme_show_nav_level|int) %} + {% if check_for_sidebar_toctree( + show_nav_level=theme_show_nav_level | int, + includehidden=theme_sidebar_includehidden | tobool + ) + %} {% 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 219a0ac73..39da3c0f4 100644 --- a/src/pydata_sphinx_theme/toctree.py +++ b/src/pydata_sphinx_theme/toctree.py @@ -40,7 +40,6 @@ def get_unrendered_local_toctree( This is similar to `context["toctree"](**kwargs)` in sphinx templating, but using the startdepth-local instead of global TOC tree. """ - kwargs.setdefault("includehidden", True) if kwargs.get("maxdepth") == "": kwargs.pop("maxdepth") @@ -460,7 +459,6 @@ def get_local_toctree_for( doctree = self.env.tocs[indexname].deepcopy() toctrees = [] - kwargs.setdefault("includehidden", True) if "maxdepth" not in kwargs or not kwargs["maxdepth"]: kwargs["maxdepth"] = 0 kwargs["maxdepth"] = int(kwargs["maxdepth"]) From 376bfba7262cc1494999263c1bb3348363aa1aa7 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 8 Jan 2024 14:57:53 -0600 Subject: [PATCH 4/5] formatting --- .../pydata_sphinx_theme/components/sidebar-nav-bs.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 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 2d52b5378..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=theme_sidebar_includehidden|tobool, + 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 ) -}} From 867dac164076a226419f6a9f96639997502e4b3b Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 9 Jan 2024 11:30:04 -0600 Subject: [PATCH 5/5] refactor and simplify toctree code --- .../theme/pydata_sphinx_theme/layout.html | 6 +- src/pydata_sphinx_theme/toctree.py | 123 +++++++++--------- 2 files changed, 61 insertions(+), 68 deletions(-) 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 cb195230c..b50dcc1be 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html @@ -82,11 +82,7 @@
{# Primary sidebar #} {# If we have no sidebar TOC, pop the TOC component from the sidebar list #} - {% if check_for_sidebar_toctree( - show_nav_level=theme_show_nav_level | int, - includehidden=theme_sidebar_includehidden | tobool - ) - %} + {% 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 39da3c0f4..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,17 +31,8 @@ def add_inline_math(node: Node) -> str: ) -def get_unrendered_local_toctree( - app: Sphinx, pagename: str, startdepth: int, collapse: bool = True, **kwargs -): - """Get the "local" (starting at `startdepth`) TOC tree containing the current page. - - This is similar to `context["toctree"](**kwargs)` in sphinx templating, - but using the startdepth-local instead of global TOC tree. - """ - 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 @@ -51,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 ) @@ -69,11 +73,18 @@ def add_toctree_functions( ) -> None: """Add functions so Jinja templates can add toctree objects.""" - def check_for_sidebar_toctree( - startdepth: int = 1, show_nav_level: int = 1, **kwargs - ): - toctree = get_unrendered_local_toctree(app, pagename, startdepth) - return toctree is not None + 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]: @@ -122,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 @@ -257,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"}): @@ -380,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["check_for_sidebar_toctree"] = check_for_sidebar_toctree + 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 @@ -445,18 +459,20 @@ 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`. + + The Sphinx equivalent is TocTree.get_toctree_for(), which always uses the "root" + or "global" TocTree: - doctree = self.env.tocs[indexname].deepcopy() + 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 "maxdepth" not in kwargs or not kwargs["maxdepth"]: @@ -464,34 +480,15 @@ def get_local_toctree_for( 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"]