369 lines · python
1# -*- coding: utf-8 -*-2#3# LLDB documentation build configuration file, created by4# sphinx-quickstart on Sun Dec 9 20:01:55 2012.5#6# This file is execfile()d with the current directory set to its containing dir.7#8# Note that not all possible configuration values are present in this9# autogenerated file.10#11# All configuration values have a default; values that are commented out12# serve to show the default.13import sys, os, re, shutil14from datetime import date15 16# Add path for llvm_slug module.17sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "llvm", "docs")))18 19building_man_page = tags.has("builder-man")20 21# For the website we need to setup the path to the generated LLDB module that22# we can generate documentation for its API.23if not building_man_page:24 # If extensions (or modules to document with autodoc) are in another directory,25 # add these directories to sys.path here. If the directory is relative to the26 # documentation root, use os.path.abspath to make it absolute, like shown here.27 28 # Add the current directory that contains the mock _lldb native module which29 # is imported by the `lldb` module.30 sys.path.insert(0, os.path.abspath("."))31 # Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is32 # set by CMake.33 sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE"))34 35# Put the generated Python API documentation in the 'python_api' folder. This36# also defines the URL these files will have in the generated website.37automodapi_toctreedirnm = "python_api"38 39# -- General configuration -----------------------------------------------------40 41# If your documentation needs a minimal Sphinx version, state it here.42# needs_sphinx = '1.0'43 44# Add any Sphinx extension module names here, as strings. They can be extensions45# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.46extensions = ["sphinx.ext.todo", "sphinx.ext.mathjax", "sphinx.ext.intersphinx"]47 48# When building man pages, we do not use the markdown pages,49# So, we can continue without the myst_parser dependencies.50# Doing so reduces dependencies of some packaged llvm distributions.51try:52 import myst_parser53 54 extensions.append("myst_parser")55except ImportError:56 if not tags.has("builder-man"):57 raise58 59# Automatic anchors for markdown titles60myst_heading_anchors = 661myst_heading_slug_func = "llvm_slug.make_slug"62 63autodoc_default_options = {"special-members": True}64 65# The suffix of source filenames.66source_suffix = {67 ".rst": "restructuredtext",68}69 70# Unless we only generate the basic manpage we need the plugin for generating71# the Python API documentation.72if not building_man_page:73 try:74 import sphinx_automodapi.automodapi75 except ModuleNotFoundError:76 print(77 f"install sphinx_automodapi with {sys.executable} -m pip install sphinx_automodapi"78 )79 extensions.append("sphinx_automodapi.automodapi")80 81 try:82 import furo83 except ModuleNotFoundError:84 print(f"install sphinx furo theme with {sys.executable} -m pip install furo")85 # The theme to use for HTML and HTML Help pages. See the documentation for86 # a list of builtin themes.87 html_theme = "furo"88 89 # Since man pages do not use markdown, we do not need to register a markdown90 # parser.91 source_suffix[".md"] = "markdown"92 93# Add any paths that contain templates here, relative to this directory.94templates_path = ["_templates"]95 96# The encoding of source files.97# source_encoding = 'utf-8-sig'98 99# The master toctree document.100master_doc = "index"101 102# General information about the project.103project = "LLDB"104copyright = "2007-%d, The LLDB Team" % date.today().year105 106# The version info for the project you're documenting, acts as replacement for107# |version| and |release|, also used in various other places throughout the108# built documents. These are currently set to zero because we don't use them.109# Should somebody consider in the future to change them, they need to be updated110# everytime a new release comes out.111#112# The short version.113# version = '0'114# The full version, including alpha/beta/rc tags.115# release = '0'116 117# The language for content autogenerated by Sphinx. Refer to documentation118# for a list of supported languages.119# language = None120 121# There are two options for replacing |today|: either, you set today to some122# non-false value, then it is used:123# today = ''124# Else, today_fmt is used as the format for a strftime call.125# today_fmt = '%B %d, %Y'126 127# List of patterns, relative to source directory, that match files and128# directories to ignore when looking for source files.129exclude_patterns = ["_build", "analyzer"]130# Ignore the generated Python documentation that is only used on the website.131# Without this we will get a lot of warnings about doc pages that aren't132# included by any doctree (as the manpage ignores those pages but they are133# potentially still around from a previous website generation).134if building_man_page:135 exclude_patterns.append(automodapi_toctreedirnm)136# Use the recommended 'any' rule so that referencing SB API classes is possible137# by just writing `SBData`.138default_role = "any"139 140# If true, '()' will be appended to :func: etc. cross-reference text.141# add_function_parentheses = True142 143# If true, the current module name will be prepended to all description144# unit titles (such as .. function::).145# add_module_names = True146 147# If true, sectionauthor and moduleauthor directives will be shown in the148# output. They are ignored by default.149# show_authors = False150 151# The name of the Pygments (syntax highlighting) style to use.152pygments_style = "friendly"153 154# A list of ignored prefixes for module index sorting.155# modindex_common_prefix = []156 157 158# -- Options for HTML output ---------------------------------------------------159 160# The theme to use for HTML and HTML Help pages. See the documentation for161# a list of builtin themes.162html_theme = "furo"163 164# Theme options are theme-specific and customize the look and feel of a theme165# further. For a list of options available for each theme, see the166# documentation.167html_theme_options = {168 "source_repository": "https://github.com/llvm/llvm-project",169 "source_branch": "main",170 "source_directory": "lldb/docs/",171}172 173# Add any paths that contain custom themes here, relative to this directory.174# html_theme_path = []175 176# The name for this set of Sphinx documents. If None, it defaults to177# "<project> v<release> documentation".178html_title = "🐛 LLDB"179 180# A shorter title for the navigation bar. Default is the same as html_title.181# html_short_title = None182 183# The name of an image file (relative to this directory) to place at the top184# of the sidebar.185# html_logo = None186 187# The name of an image file (within the static path) to use as favicon of the188# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32189# pixels large.190# html_favicon = None191 192# Add any paths that contain custom static files (such as style sheets) here,193# relative to this directory. They are copied after the builtin static files,194# so a file named "default.css" will overwrite the builtin "default.css".195# html_static_path = ["_static"]196 197html_extra_path = [".htaccess"]198 199# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,200# using the given strftime format.201html_last_updated_fmt = "%b %d, %Y"202 203# If true, SmartyPants will be used to convert quotes and dashes to204# typographically correct entities.205# html_use_smartypants = True206 207# Custom sidebar templates, maps document names to template names.208# html_sidebars = {}209 210# Additional templates that should be rendered to pages, maps page names to211# template names.212# html_additional_pages = {}213 214# If false, no module index is generated.215# html_domain_indices = True216 217# If false, no index is generated.218# html_use_index = True219 220# If true, the index is split into individual pages for each letter.221# html_split_index = False222 223# If true, links to the reST sources are added to the pages.224# html_show_sourcelink = True225 226# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.227# html_show_sphinx = True228 229# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.230# html_show_copyright = True231 232# If true, an OpenSearch description file will be output, and all pages will233# contain a <link> tag referring to it. The value of this option must be the234# base URL from which the finished HTML is served.235# html_use_opensearch = ''236 237# This is the file name suffix for HTML files (e.g. ".xhtml").238# html_file_suffix = None239 240# Output file base name for HTML help builder.241htmlhelp_basename = "LLDBdoc"242 243# If true, the reST sources are included in the HTML build as244# _sources/name. The default is True.245html_copy_source = False246 247# -- Options for LaTeX output --------------------------------------------------248 249latex_elements = {250 # The paper size ('letterpaper' or 'a4paper').251 #'papersize': 'letterpaper',252 # The font size ('10pt', '11pt' or '12pt').253 #'pointsize': '10pt',254 # Additional stuff for the LaTeX preamble.255 #'preamble': '',256}257 258# Grouping the document tree into LaTeX files. List of tuples259# (source start file, target name, title, author, documentclass [howto/manual]).260latex_documents = [261 ("index", "LLDB.tex", "LLDB Documentation", "The LLDB Team", "manual"),262]263 264# The name of an image file (relative to this directory) to place at the top of265# the title page.266# latex_logo = None267 268# For "manual" documents, if this is true, then toplevel headings are parts,269# not chapters.270# latex_use_parts = False271 272# If true, show page references after internal links.273# latex_show_pagerefs = False274 275# If true, show URL addresses after external links.276# latex_show_urls = False277 278# Documents to append as an appendix to all manuals.279# latex_appendices = []280 281# If false, no module index is generated.282# latex_domain_indices = True283 284 285# -- Options for manual page output --------------------------------------------286 287# One entry per manual page. List of tuples288# (source start file, name, description, authors, manual section).289man_pages = [290 ("man/lldb", "lldb", "LLDB Documentation", ["LLVM project"], 1),291 ("man/lldb-server", "lldb-server", "LLDB Documentation", ["LLVM project"], 1),292]293 294# If true, show URL addresses after external links.295# man_show_urls = False296 297# -- Options for Texinfo output ------------------------------------------------298 299# Grouping the document tree into Texinfo files. List of tuples300# (source start file, target name, title, author,301# dir menu entry, description, category)302texinfo_documents = [303 (304 "index",305 "LLDB",306 "LLDB Documentation",307 "The LLDB Team",308 "LLDB",309 "One line description of project.",310 "Miscellaneous",311 ),312]313 314# Documents to append as an appendix to all manuals.315# texinfo_appendices = []316 317# If false, no module index is generated.318# texinfo_domain_indices = True319 320# How to display URL addresses: 'footnote', 'no', or 'inline'.321# texinfo_show_urls = 'footnote'322 323empty_attr_summary = re.compile(324 r"\.\. rubric:: Attributes Summary\s*\.\. autosummary::\s*\.\. rubric::"325)326empty_attr_documentation = re.compile(327 r"\.\. rubric:: Attributes Documentation\s*\.\. rubric::"328)329 330 331def preprocess_source(app, docname, source):332 """Preprocesses source files generated by automodapi."""333 # Don't cleanup anything beside automodapi-generated sources.334 if not automodapi_toctreedirnm in docname:335 return336 processed = source[0]337 338 # Don't show the list of inheritance info as there is no inheritance in the339 # SBI API. This avoids all the repeated text on all doc pages that a340 # class inherits from 'object'.341 342 processed = processed.replace(":show-inheritance:", "")343 # Remove the SWIG generated 'thisown' attribute. It just bloats the generated344 # documentation and users shouldn't fiddle with the value anyway.345 processed = re.sub(r"~SB[a-zA-Z]+\.thisown", "", processed)346 processed = processed.replace(" .. autoattribute:: thisown", "")347 348 # After removing 'thisown', many objects don't have any attributes left.349 # Remove all now empty attribute summary/documentation sections with350 # some rather ugly regex.351 processed = empty_attr_summary.sub(".. rubric::", processed)352 processed = empty_attr_documentation.sub(".. rubric::", processed)353 354 # Replace the original source with the processed one (source is a single355 # element list).356 source[0] = processed357 358 359def cleanup_source(app, exception):360 """Remove files generated by automodapi in the source tree."""361 if hasattr(app.config, "automodapi_toctreedirnm"):362 api_source_dir = os.path.join(app.srcdir, app.config.automodapi_toctreedirnm)363 shutil.rmtree(api_source_dir, ignore_errors=True)364 365 366def setup(app):367 app.connect("source-read", preprocess_source)368 app.connect("build-finished", cleanup_source)369