1# -*- coding: utf-8 -*- 2# 3# LLDB documentation build configuration file, created by 4# 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 this 9# autogenerated file. 10# 11# All configuration values have a default; values that are commented out 12# serve to show the default. 13from __future__ import print_function 14 15import sys, os, re, shutil 16from datetime import date 17 18building_man_page = tags.has('builder-man') 19 20# For the website we need to setup the path to the generated LLDB module that 21# we can generate documentation for its API. 22if not building_man_page: 23 # If extensions (or modules to document with autodoc) are in another directory, 24 # add these directories to sys.path here. If the directory is relative to the 25 # documentation root, use os.path.abspath to make it absolute, like shown here. 26 27 # Add the current directory that contains the mock _lldb native module which 28 # is imported by the `lldb` module. 29 sys.path.insert(0, os.path.abspath(".")) 30 # Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is 31 # set by CMake. 32 sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE")) 33 34# Put the generated Python API documentation in the 'python_api' folder. This 35# also defines the URL these files will have in the generated website. 36automodapi_toctreedirnm = 'python_api' 37 38# -- General configuration ----------------------------------------------------- 39 40# If your documentation needs a minimal Sphinx version, state it here. 41#needs_sphinx = '1.0' 42 43# Add any Sphinx extension module names here, as strings. They can be extensions 44# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 45extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx'] 46 47autodoc_default_options = { 48 'special-members': '__int__, __len__, __hex__, __oct__, __iter__', 49} 50 51# Unless we only generate the basic manpage we need the plugin for generating 52# the Python API documentation. 53if not building_man_page: 54 extensions.append('sphinx_automodapi.automodapi') 55 56# Add any paths that contain templates here, relative to this directory. 57templates_path = ['_templates'] 58 59# The suffix of source filenames. 60source_suffix = { 61 '.rst': 'restructuredtext', 62} 63 64# The encoding of source files. 65#source_encoding = 'utf-8-sig' 66 67# The master toctree document. 68master_doc = 'index' 69 70# General information about the project. 71project = u'LLDB' 72copyright = u'2007-%d, The LLDB Team' % date.today().year 73 74# The version info for the project you're documenting, acts as replacement for 75# |version| and |release|, also used in various other places throughout the 76# built documents. These are currently set to zero because we don't use them. 77# Should somebody consider in the future to change them, they need to be updated 78# everytime a new release comes out. 79# 80# The short version. 81#version = '0' 82# The full version, including alpha/beta/rc tags. 83#release = '0' 84 85# The language for content autogenerated by Sphinx. Refer to documentation 86# for a list of supported languages. 87#language = None 88 89# There are two options for replacing |today|: either, you set today to some 90# non-false value, then it is used: 91#today = '' 92# Else, today_fmt is used as the format for a strftime call. 93#today_fmt = '%B %d, %Y' 94 95# List of patterns, relative to source directory, that match files and 96# directories to ignore when looking for source files. 97exclude_patterns = ['_build', 'analyzer'] 98# Ignore the generated Python documentation that is only used on the website. 99# Without this we will get a lot of warnings about doc pages that aren't 100# included by any doctree (as the manpage ignores those pages but they are 101# potentially still around from a previous website generation). 102if building_man_page: 103 exclude_patterns.append(automodapi_toctreedirnm) 104# Use the recommended 'any' rule so that referencing SB API classes is possible 105# by just writing `SBData`. 106default_role = 'any' 107 108# If true, '()' will be appended to :func: etc. cross-reference text. 109#add_function_parentheses = True 110 111# If true, the current module name will be prepended to all description 112# unit titles (such as .. function::). 113#add_module_names = True 114 115# If true, sectionauthor and moduleauthor directives will be shown in the 116# output. They are ignored by default. 117#show_authors = False 118 119# The name of the Pygments (syntax highlighting) style to use. 120pygments_style = 'friendly' 121 122# A list of ignored prefixes for module index sorting. 123#modindex_common_prefix = [] 124 125 126# -- Options for HTML output --------------------------------------------------- 127 128# The theme to use for HTML and HTML Help pages. See the documentation for 129# a list of builtin themes. 130html_theme = 'alabaster' 131 132# Theme options are theme-specific and customize the look and feel of a theme 133# further. For a list of options available for each theme, see the 134# documentation. 135html_theme_options = { 136 'font_size': '11pt', 137 # Don't generate any links to GitHub. 138 'github_button' : 'false', 139} 140 141# Add any paths that contain custom themes here, relative to this directory. 142#html_theme_path = [] 143 144# The name for this set of Sphinx documents. If None, it defaults to 145# "<project> v<release> documentation". 146html_title = 'The LLDB Debugger' 147 148# A shorter title for the navigation bar. Default is the same as html_title. 149#html_short_title = None 150 151# The name of an image file (relative to this directory) to place at the top 152# of the sidebar. 153#html_logo = None 154 155# The name of an image file (within the static path) to use as favicon of the 156# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 157# pixels large. 158#html_favicon = None 159 160# Add any paths that contain custom static files (such as style sheets) here, 161# relative to this directory. They are copied after the builtin static files, 162# so a file named "default.css" will overwrite the builtin "default.css". 163html_static_path = ['_static'] 164 165html_context = { 166 'css_files': [ 167 '_static/lldb.css' 168 ], 169 } 170 171html_extra_path = ['.htaccess'] 172 173# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 174# using the given strftime format. 175html_last_updated_fmt = '%b %d, %Y' 176 177# If true, SmartyPants will be used to convert quotes and dashes to 178# typographically correct entities. 179#html_use_smartypants = True 180 181# Custom sidebar templates, maps document names to template names. 182#html_sidebars = {} 183 184# Additional templates that should be rendered to pages, maps page names to 185# template names. 186#html_additional_pages = {} 187 188# If false, no module index is generated. 189#html_domain_indices = True 190 191# If false, no index is generated. 192#html_use_index = True 193 194# If true, the index is split into individual pages for each letter. 195#html_split_index = False 196 197# If true, links to the reST sources are added to the pages. 198#html_show_sourcelink = True 199 200# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 201#html_show_sphinx = True 202 203# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 204#html_show_copyright = True 205 206# If true, an OpenSearch description file will be output, and all pages will 207# contain a <link> tag referring to it. The value of this option must be the 208# base URL from which the finished HTML is served. 209#html_use_opensearch = '' 210 211# This is the file name suffix for HTML files (e.g. ".xhtml"). 212#html_file_suffix = None 213 214# Output file base name for HTML help builder. 215htmlhelp_basename = 'LLDBdoc' 216 217# If true, the reST sources are included in the HTML build as 218# _sources/name. The default is True. 219html_copy_source = False 220 221# -- Options for LaTeX output -------------------------------------------------- 222 223latex_elements = { 224# The paper size ('letterpaper' or 'a4paper'). 225#'papersize': 'letterpaper', 226 227# The font size ('10pt', '11pt' or '12pt'). 228#'pointsize': '10pt', 229 230# Additional stuff for the LaTeX preamble. 231#'preamble': '', 232} 233 234# Grouping the document tree into LaTeX files. List of tuples 235# (source start file, target name, title, author, documentclass [howto/manual]). 236latex_documents = [ 237 ('index', 'LLDB.tex', u'LLDB Documentation', 238 u'The LLDB Team', 'manual'), 239] 240 241# The name of an image file (relative to this directory) to place at the top of 242# the title page. 243#latex_logo = None 244 245# For "manual" documents, if this is true, then toplevel headings are parts, 246# not chapters. 247#latex_use_parts = False 248 249# If true, show page references after internal links. 250#latex_show_pagerefs = False 251 252# If true, show URL addresses after external links. 253#latex_show_urls = False 254 255# Documents to append as an appendix to all manuals. 256#latex_appendices = [] 257 258# If false, no module index is generated. 259#latex_domain_indices = True 260 261 262# -- Options for manual page output -------------------------------------------- 263 264# One entry per manual page. List of tuples 265# (source start file, name, description, authors, manual section). 266man_pages = [('man/lldb', 'lldb', u'LLDB Documentation', [u'LLVM project'], 1), 267 ('man/lldb-server', 'lldb-server', u'LLDB Documentation', [u'LLVM project'], 1), 268 ] 269 270# If true, show URL addresses after external links. 271#man_show_urls = False 272 273# -- Options for Texinfo output ------------------------------------------------ 274 275# Grouping the document tree into Texinfo files. List of tuples 276# (source start file, target name, title, author, 277# dir menu entry, description, category) 278texinfo_documents = [ 279 ('index', 'LLDB', u'LLDB Documentation', 280 u'The LLDB Team', 'LLDB', 'One line description of project.', 281 'Miscellaneous'), 282] 283 284# Documents to append as an appendix to all manuals. 285#texinfo_appendices = [] 286 287# If false, no module index is generated. 288#texinfo_domain_indices = True 289 290# How to display URL addresses: 'footnote', 'no', or 'inline'. 291#texinfo_show_urls = 'footnote' 292 293empty_attr_summary = re.compile(r'\.\. rubric:: Attributes Summary\s*\.\. autosummary::\s*\.\. rubric::') 294empty_attr_documentation = re.compile(r'\.\. rubric:: Attributes Documentation\s*\.\. rubric::') 295 296def preprocess_source(app, docname, source): 297 """ Preprocesses source files generated by automodapi. """ 298 # Don't cleanup anything beside automodapi-generated sources. 299 if not automodapi_toctreedirnm in docname: 300 return 301 processed = source[0] 302 303 # Don't show the list of inheritance info as there is no inheritance in the 304 # SBI API. This avoids all the repeated text on all doc pages that a 305 # class inherits from 'object'. 306 307 processed = processed.replace(":show-inheritance:", "") 308 # Remove the SWIG generated 'thisown' attribute. It just bloats the generated 309 # documentation and users shouldn't fiddle with the value anyway. 310 processed = re.sub(r'~SB[a-zA-Z]+\.thisown', "", processed) 311 processed = processed.replace(" .. autoattribute:: thisown", "") 312 313 # After removing 'thisown', many objects don't have any attributes left. 314 # Remove all now empty attribute summary/documentation sections with 315 # some rather ugly regex. 316 processed = empty_attr_summary.sub('.. rubric::', processed) 317 processed = empty_attr_documentation.sub('.. rubric::', processed) 318 319 # Replace the original source with the processed one (source is a single 320 # element list). 321 source[0] = processed 322 323def cleanup_source(app, exception): 324 """ Remove files generated by automodapi in the source tree. """ 325 if hasattr(app.config, 'automodapi_toctreedirnm'): 326 api_source_dir = os.path.join(app.srcdir, app.config.automodapi_toctreedirnm) 327 shutil.rmtree(api_source_dir, ignore_errors=True) 328 329def setup(app): 330 app.connect('source-read', preprocess_source) 331 app.connect('build-finished', cleanup_source) 332