"""Methods to build the toctree used in the html pages."""fromdataclassesimportdataclassfromfunctoolsimportcachefromitertoolsimportcountfromtextwrapimportdedentfromtypingimportIterator,List,Tuple,Unionfromurllib.parseimporturlparseimportsphinxfrombs4importBeautifulSoupfromdocutilsimportnodesfromdocutils.nodesimportNodefromsphinx.addnodesimporttoctreeasTocTreeNodeClassfromsphinx.applicationimportSphinxfromsphinx.environment.adapters.toctreeimportTocTreefromsphinx.localeimport_from.utilsimporttraverse_or_findall
[文档]defadd_inline_math(node:Node)->str:"""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 """return('<span class="math notranslate nohighlight">'rf"\({node.astext()}\)""</span>")
[文档]def_get_ancestor_pagename(app:Sphinx,pagename:str,startdepth:int)->str:""" Get the name of `pagename`'s ancestor that is rooted `startdepth` levels below the global root. """toctree=TocTree(app.env)ifsphinx.version_info[:2]>=(7,2):fromsphinx.environment.adapters.toctreeimport_get_toctree_ancestorsancestors=[*_get_toctree_ancestors(app.env.toctree_includes,pagename)]else:ancestors=toctree.get_toctree_ancestors(pagename)try:out=ancestors[-startdepth]exceptIndexError:# 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 None instead of using the default sphinx# toctree.get_toctree_for(pagename, app.builder, collapse, **kwargs)out=Nonereturnout,toctree
@dataclass
[文档]classLinkInfo:"""Dataclass to generate toctree data."""
[文档]defadd_toctree_functions(app:Sphinx,pagename:str,templatename:str,context,doctree)->None:"""Add functions so Jinja templates can add toctree objects."""defsuppress_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. """ancestorname,toctree_obj=_get_ancestor_pagename(app=app,pagename=pagename,startdepth=startdepth)ifancestornameisNone:returnTrue# suppressifkwargs.get("includehidden",False):# if ancestor is found and `includehidden=True` we're guaranteed there's a# TocTree to be shown, so don't suppressreturnFalse# we've found an ancestor page, but `includehidden=False` so we can't be sure if# there's a TocTree fragment that should be shown on this page; unfortunately we# must resolve the whole TOC subtree to find outtoctree=get_nonroot_toctree(app,pagename,ancestorname,toctree_obj,**kwargs)returntoctreeisNone@cachedefget_or_create_id_generator(base_id:str)->Iterator[str]:fornincount(start=1):ifn==1:yieldbase_idelse:yieldf"{base_id}-{n}"defunique_html_id(base_id:str):""" Create an id that is unique from other ids created by this function at build time. The function works by sequentially returning "<base_id>", "<base_id>-2", "<base_id>-3", etc. each time it is called. """returnnext(get_or_create_id_generator(base_id))@cachedef_generate_nav_info()->List[LinkInfo]:"""Generate informations necessary to generate nav. Instead of messing with html later, having this as a util function should make it slightly easier to generate different html snippet for sidebar or navbar. """toctree=TocTree(app.env)# Find the active header navigation item so we decide whether to highlight# Will be empty if there is no active page (root_doc, or genindex etc)ifsphinx.version_info[:2]>=(7,2):fromsphinx.environment.adapters.toctreeimport_get_toctree_ancestors# NOTE: `env.toctree_includes` is a dict mapping pagenames to any (possibly# hidden) TocTree directives on that page (i.e., the "child" pages nested# under `pagename`).header_pages=[*_get_toctree_ancestors(app.env.toctree_includes,pagename)]else:header_pages=toctree.get_toctree_ancestors(pagename)ifheader_pages:# The final list item will be the top-most ancestoractive_header_page=header_pages[-1]else:active_header_page=None# NOTE: `env.tocs` is a dict mapping pagenames to hierarchical bullet-lists# ("nodetrees" in Sphinx parlance) of in-page headings (including `toctree::`# directives). Thus the `tocs` of `root_doc` yields the top-level pages that sit# just below the root of our siteroot_toc=app.env.tocs[app.config.root_doc]links_data=[]# Iterate through each node in the root document toc.# Grab the toctree pages and find the relative link + title.fortocintraverse_or_findall(root_toc,TocTreeNodeClass):# TODO: ↑↑↑ use `root_toc.findall(TocTreeNodeClass)` ↑↑↑# once docutils min version >=0.18.1fortitle,pageintoc.attributes["entries"]:# if the page is using "self" use the correct linkpage=toc.attributes["parent"]ifpage=="self"elsepage# If this is the active ancestor page, add a class so we highlight it# sanitize page title for use in the html output if needediftitleisNone:title=""fornodeinapp.env.titles[page].children:ifisinstance(node,nodes.math):title+=add_inline_math(node)else:title+=node.astext()# set up the status of the link and the path# if the path is relative then we use the context for the path# resolution and the internal class.# If it's an absolute one then we use the external class and# the complete url.is_absolute=bool(urlparse(page).netloc)link_href=pageifis_absoluteelsecontext["pathto"](page)links_data.append(LinkInfo(is_current=(page==active_header_page),href=link_href,title=title,is_external=is_absolute,))# Add external links defined in configuration as sibling list itemsforexternal_linkincontext["theme_external_links"]:links_data.append(LinkInfo(is_current=False,href=external_link["url"],title=external_link["name"],is_external=True,))returnlinks_data@cachedef_generate_header_nav_before_dropdown(n_links_before_dropdown,)->Tuple[str,List[str]]:"""Return html for navbar and dropdown. Given the number of links before the dropdown, return the html for the navbar, as well as the list of links to put in a dropdown. Returns: - HTML str for the navbar - list of HTML str for the dropdown """try:n_links_before_dropdown=int(n_links_before_dropdown)exceptException:raiseValueError(f"n_links_before_dropdown is not an int: {n_links_before_dropdown}")links_data=_generate_nav_info()links_html=[]links_dropdown=[]boilerplate=dedent(""" <li class="{nav_item} {active}"> <a class="{nav_link} nav-{ext_int}" href="{href}"> {title} </a> </li> """)nav_item="nav-item"nav_link="nav-link"dropdown_item="dropdown-item"forlinkinlinks_data[:n_links_before_dropdown]:links_html.append(boilerplate.format(active="current active"iflink.is_currentelse"",nav_link=nav_link,nav_item=nav_item,ext_int="external"iflink.is_externalelse"internal",href=link.href,title=link.title,))forlinkinlinks_data[n_links_before_dropdown:]:links_dropdown.append(boilerplate.format(active="current active"iflink.is_currentelse"",nav_link=nav_link+" "+dropdown_item,nav_item="",ext_int="external"iflink.is_externalelse"internal",href=link.href,title=link.title,))# The first links will always be visiblereturn"\n".join(links_html),links_dropdowndefgenerate_header_nav_html(n_links_before_dropdown:int=5,dropdown_text:str="More")->str:"""Generate top-level links that are meant for the header navigation. We use this function instead of the TocTree-based one used for the sidebar because this one is much faster for generating the links and we don't need the complexity of the full Sphinx TocTree. This includes two kinds of links: - Links to pages described listed in the root_doc TocTrees - External links defined in theme configuration Additionally it will create a dropdown list for several links after a cutoff. Parameters: n_links_before_dropdown:The number of links to show before nesting the remaining links in a Dropdown element. dropdown_text:Text of the dropdown element button. """out,links_dropdown=_generate_header_nav_before_dropdown(n_links_before_dropdown)iflinks_dropdown:dropdown_id=unique_html_id("pst-nav-more-links")links_dropdown_html="\n".join(links_dropdown)out+=f""" <li class="nav-item dropdown"> <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="{dropdown_id}">{_(dropdown_text)} </button> <ul id="{dropdown_id}" class="dropdown-menu">{links_dropdown_html} </ul> </li> """returnout# Cache this function because it is expensive to run, and because Sphinx# somehow runs this twice in some circumstances in unpredictable ways.@cachedefgenerate_toctree_html(kind:str,startdepth:int=1,show_nav_level:int=1,**kwargs)->Union[BeautifulSoup,str]:"""Return the navigation link structure in HTML. This is similar to Sphinx's own default TocTree generation, but it is modified to generate TocTrees for *second*-level pages and below (not supported by default in Sphinx). This is used for our sidebar, which starts at the second-level page. It also modifies the generated TocTree slightly for Bootstrap classes and structure (via BeautifulSoup). Arguments are passed to Sphinx "toctree" function (context["toctree"] below). ref: https://www.sphinx-doc.org/en/master/templating.html#toctree Parameters: kind : "sidebar" or "raw". Whether to generate HTML meant for sidebar navigation ("sidebar") or to return the raw BeautifulSoup object ("raw"). startdepth : The level of the toctree at which to start. By default, for the navbar uses the normal toctree (`startdepth=0`), and for the sidebar starts from the second level (`startdepth=1`). show_nav_level : The level of the navigation bar to toggle as visible on page load. By default, this level is 1, and only top-level pages are shown, with drop-boxes to reveal children. Increasing `show_nav_level` will show child levels as well. kwargs : passed to the Sphinx `toctree` template function. Returns: HTML string (if kind == "sidebar") OR BeautifulSoup object (if kind == "raw") """ifstartdepth==0:html_toctree=context["toctree"](**kwargs)else:# find relevant ancestor page; some pages (search, genindex) won't have oneancestorname,toctree_obj=_get_ancestor_pagename(app=app,pagename=pagename,startdepth=startdepth)ifancestornameisNone:raiseRuntimeError("Template requested to generate a TocTree fragment but no suitable ""ancestor found to act as root node. Please report this to theme ""developers.")# select the "active" subset of the navigation tree for the sidebartoctree_element=get_nonroot_toctree(app,pagename,ancestorname,toctree_obj,**kwargs)html_toctree=app.builder.render_partial(toctree_element)["fragment"]soup=BeautifulSoup(html_toctree,"html.parser")# pair "current" with "active" since that's what we use w/ bootstrapforliinsoup("li",{"class":"current"}):li["class"].append("active")# Remove sidebar links to sub-headers on the pageforliinsoup.select("li"):# Removeifli.find("a"):href=li.find("a")["href"]if"#"inhrefandhref!="#":li.decompose()ifkind=="sidebar":# Add bootstrap classes for first `ul` itemsforulinsoup("ul",recursive=False):ul.attrs["class"]=[*ul.attrs.get("class",[]),"nav","bd-sidenav"]# Add collapse boxes for parts/captions.# Wraps the TOC part in an extra <ul> to behave like chapters with toggles# show_nav_level: 0 means make parts collapsible.ifshow_nav_level==0:partcaptions=soup.find_all("p",attrs={"class":"caption"})iflen(partcaptions):new_soup=BeautifulSoup("<ul class='list-caption'></ul>","html.parser")forcaptioninpartcaptions:# Assume that the next <ul> element is the TOC list# for this partforsiblingincaption.next_siblings:ifsibling.name=="ul":toclist=siblingbreakli=soup.new_tag("li",attrs={"class":"toctree-l0"})li.extend([caption,toclist])new_soup.ul.append(li)soup=new_soup# Add icons and labels for collapsible nested sectionsadd_collapse_checkboxes(soup)# Open the sidebar navigation to the proper depthforiiinrange(int(show_nav_level)):fordetailsinsoup.select(f"li.toctree-l{ii} > details"):details["open"]="open"returnsoup@cachedefgenerate_toc_html(kind:str="html")->BeautifulSoup:"""Return the within-page TOC links in HTML."""if"toc"notincontext:return""soup=BeautifulSoup(context["toc"],"html.parser")# Add toc-hN + visible classesdefadd_header_level_recursive(ul,level):ifulisNone:returniflevel<=(context["theme_show_toc_level"]+1):ul["class"]=[*ul.get("class",[]),"visible"]forliinul("li",recursive=False):li["class"]=[*li.get("class",[]),f"toc-h{level}"]add_header_level_recursive(li.find("ul",recursive=False),level+1)add_header_level_recursive(soup.find("ul"),1)# Add in CSS classes for bootstrapforulinsoup("ul"):ul["class"]=[*ul.get("class",[]),"nav","section-nav","flex-column"]forliinsoup("li"):li["class"]=[*li.get("class",[]),"nav-item","toc-entry"]ifli.find("a"):a=li.find("a")a["class"]=[*a.get("class",[]),"nav-link"]# If we only have one h1 header, assume it's a titleh1_headers=soup.select(".toc-h1")iflen(h1_headers)==1:title=h1_headers[0]# If we have no sub-headers of a title then we won't have a TOCifnottitle.select(".toc-h2"):out=""else:out=title.find("ul")# Else treat the h1 headers as sectionselse:out=soup# Return the toctree objectifkind=="html":returnoutelse:returnsoupdefnavbar_align_class()->List[str]:"""Return the class that aligns the navbar based on config."""align=context.get("theme_navbar_align","content")align_options={"content":("col-lg-3","col-lg-9","me-auto"),"left":("","","me-auto"),"right":("","","ms-auto"),}ifalignnotinalign_options:raiseValueError("Theme option navbar_align must be one of"f"{align_options.keys()}, got: {align}")returnalign_options[align]context["unique_html_id"]=unique_html_idcontext["generate_header_nav_html"]=generate_header_nav_htmlcontext["suppress_sidebar_toctree"]=suppress_sidebar_toctreecontext["generate_toctree_html"]=generate_toctree_htmlcontext["generate_toc_html"]=generate_toc_htmlcontext["navbar_align_class"]=navbar_align_class
[文档]defadd_collapse_checkboxes(soup:BeautifulSoup)->None:"""Add checkboxes to collapse children in a toctree."""# based on https://github.com/pradyunsg/furoforelementinsoup.find_all("li",recursive=True):# We check all "li" elements, to add a "current-page" to the correct li.classes=element.get("class",[])# expanding the parent part explicitly, if presentif"current"inclasses:parentli=element.find_parent("li",class_="toctree-l0")ifparentli:parentli.find("details")["open"]=None# Nothing more to do, unless this has "children"ifnotelement.find("ul"):continue# Add a class to indicate that this has children.element["class"]=[*classes,"has-children"]ifsoup.new_tagisNone:continue# For table of contents nodes that have subtrees, we modify the HTML so# that the subtree can be expanded or collapsed in the browser.## The HTML markup tree at the parent node starts with this structure:## - li.has-children# - a.reference or p.caption# - ul## Note the first child of li.has-children is p.caption only if this node# is a section heading. (This only happens when show_nav_level is set to# 0.)## Now we modify the tree structure in one of two ways.## (1) If the node holds a section heading, the HTML tree will be# modified like so:## - li.has-children# - details# - summary# - p.caption# - .toctree-toggle# - ul## (2) Otherwise, if the node holds a link to a page in the docs:## - li.has-children# - a.reference# - details# - summary# - .toctree-toggle# - ul## Why the difference? In the first case, the TOC section heading is not# a link, but in the second case it is. So in the first case it makes# sense to put the (non-link) text inside the summary tag so that the# user can click either the text or the .toctree-toggle chevron icon to# expand/collapse the TOC subtree. But in the second case, putting the# link in the summary tag would make it unclear whether clicking on the# link should expand the subtree or take you to the link.# Create <details> and put the entire subtree into itdetails=soup.new_tag("details")details.extend(element.contents)element.append(details)# Hoist the link to the top if there is onetoc_link=element.select_one("details > a.reference")iftoc_link:element.insert(0,toc_link)# Create <summary> with chevron iconsummary=soup.new_tag("summary")span=soup.new_tag("span",attrs={"class":"toctree-toggle",# This element and the chevron it contains are purely decorative;# the actual expand/collapse functionality is delegated to the# <summary> tag"role":"presentation",},)span.append(soup.new_tag("i",attrs={"class":"fa-solid fa-chevron-down"}))summary.append(span)# Prepend section heading (if there is one) to <summary>collapsible_section_heading=element.select_one("details > p.caption")ifcollapsible_section_heading:# Put heading inside summary so that the heading text (and chevron) are both# clickablesummary.insert(0,collapsible_section_heading)# Prepend <summary> to <details>details.insert(0,summary)# If this TOC node has a "current" class, be expanded by default# (by opening the details/summary disclosure widget)if"current"inclasses:details["open"]="open"
[文档]defget_nonroot_toctree(app:Sphinx,pagename:str,ancestorname:str,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)`). """kwargs.setdefault("collapse",True)if"maxdepth"notinkwargsornotkwargs["maxdepth"]:kwargs["maxdepth"]=0kwargs["maxdepth"]=int(kwargs["maxdepth"])# starting from ancestor page, recursively parse `toctree::` elementsancestor_doctree=toctree.env.tocs[ancestorname].deepcopy()toctrees=[]# for each `toctree::` directive in the ancestor page...fortoctree_nodeintraverse_or_findall(ancestor_doctree,TocTreeNodeClass):# TODO: ↑↑↑↑↑↑ use `ancestor_doctree.findall(TocTreeNodeClass)` ↑↑↑↑↑↑# once docutils min version >=0.18.1# ... resolve that `toctree::` (recursively get children, prune, collapse, etc)resolved_toctree=toctree.resolve(docname=pagename,builder=app.builder,toctree=toctree_node,**kwargs,)# ... keep the non-empty onesifresolved_toctree:toctrees.append(resolved_toctree)ifnottoctrees:returnNone# ... and merge them into a single entityresult=toctrees[0]forresolved_toctreeintoctrees[1:]:result.extend(resolved_toctree.children)returnresult