1061da546Spatrick# -*- coding: utf-8 -*- 2061da546Spatrick# 3061da546Spatrick# LLDB documentation build configuration file, created by 4061da546Spatrick# sphinx-quickstart on Sun Dec 9 20:01:55 2012. 5061da546Spatrick# 6061da546Spatrick# This file is execfile()d with the current directory set to its containing dir. 7061da546Spatrick# 8061da546Spatrick# Note that not all possible configuration values are present in this 9061da546Spatrick# autogenerated file. 10061da546Spatrick# 11061da546Spatrick# All configuration values have a default; values that are commented out 12061da546Spatrick# serve to show the default. 13be691f3bSpatrickfrom __future__ import print_function 14061da546Spatrick 15*f6aab3d8Srobertimport sys, os, re, shutil 16061da546Spatrickfrom datetime import date 17061da546Spatrick 18be691f3bSpatrickbuilding_man_page = tags.has('builder-man') 19be691f3bSpatrick 20be691f3bSpatrick# For the website we need to setup the path to the generated LLDB module that 21be691f3bSpatrick# we can generate documentation for its API. 22be691f3bSpatrickif not building_man_page: 23061da546Spatrick # If extensions (or modules to document with autodoc) are in another directory, 24061da546Spatrick # add these directories to sys.path here. If the directory is relative to the 25061da546Spatrick # documentation root, use os.path.abspath to make it absolute, like shown here. 26be691f3bSpatrick 27be691f3bSpatrick # Add the current directory that contains the mock _lldb native module which 28be691f3bSpatrick # is imported by the `lldb` module. 29be691f3bSpatrick sys.path.insert(0, os.path.abspath(".")) 30be691f3bSpatrick # Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is 31be691f3bSpatrick # set by CMake. 32be691f3bSpatrick sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE")) 33be691f3bSpatrick 34be691f3bSpatrick# Put the generated Python API documentation in the 'python_api' folder. This 35be691f3bSpatrick# also defines the URL these files will have in the generated website. 36be691f3bSpatrickautomodapi_toctreedirnm = 'python_api' 37061da546Spatrick 38061da546Spatrick# -- General configuration ----------------------------------------------------- 39061da546Spatrick 40061da546Spatrick# If your documentation needs a minimal Sphinx version, state it here. 41061da546Spatrick#needs_sphinx = '1.0' 42061da546Spatrick 43061da546Spatrick# Add any Sphinx extension module names here, as strings. They can be extensions 44061da546Spatrick# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 45061da546Spatrickextensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx'] 46061da546Spatrick 47be691f3bSpatrickautodoc_default_options = { 48be691f3bSpatrick 'special-members': '__int__, __len__, __hex__, __oct__, __iter__', 49be691f3bSpatrick} 50be691f3bSpatrick 51be691f3bSpatrick# Unless we only generate the basic manpage we need the plugin for generating 52be691f3bSpatrick# the Python API documentation. 53be691f3bSpatrickif not building_man_page: 54be691f3bSpatrick extensions.append('sphinx_automodapi.automodapi') 55be691f3bSpatrick 56061da546Spatrick# Add any paths that contain templates here, relative to this directory. 57061da546Spatricktemplates_path = ['_templates'] 58061da546Spatrick 59061da546Spatrick# The suffix of source filenames. 60be691f3bSpatricksource_suffix = { 61be691f3bSpatrick '.rst': 'restructuredtext', 62be691f3bSpatrick} 63be691f3bSpatrick 64061da546Spatrick# The encoding of source files. 65061da546Spatrick#source_encoding = 'utf-8-sig' 66061da546Spatrick 67061da546Spatrick# The master toctree document. 68061da546Spatrickmaster_doc = 'index' 69061da546Spatrick 70061da546Spatrick# General information about the project. 71061da546Spatrickproject = u'LLDB' 72061da546Spatrickcopyright = u'2007-%d, The LLDB Team' % date.today().year 73061da546Spatrick 74061da546Spatrick# The version info for the project you're documenting, acts as replacement for 75061da546Spatrick# |version| and |release|, also used in various other places throughout the 76dda28197Spatrick# built documents. These are currently set to zero because we don't use them. 77dda28197Spatrick# Should somebody consider in the future to change them, they need to be updated 78dda28197Spatrick# everytime a new release comes out. 79061da546Spatrick# 80061da546Spatrick# The short version. 81dda28197Spatrick#version = '0' 82061da546Spatrick# The full version, including alpha/beta/rc tags. 83dda28197Spatrick#release = '0' 84061da546Spatrick 85061da546Spatrick# The language for content autogenerated by Sphinx. Refer to documentation 86061da546Spatrick# for a list of supported languages. 87061da546Spatrick#language = None 88061da546Spatrick 89061da546Spatrick# There are two options for replacing |today|: either, you set today to some 90061da546Spatrick# non-false value, then it is used: 91061da546Spatrick#today = '' 92061da546Spatrick# Else, today_fmt is used as the format for a strftime call. 93061da546Spatrick#today_fmt = '%B %d, %Y' 94061da546Spatrick 95061da546Spatrick# List of patterns, relative to source directory, that match files and 96061da546Spatrick# directories to ignore when looking for source files. 97061da546Spatrickexclude_patterns = ['_build', 'analyzer'] 98be691f3bSpatrick# Ignore the generated Python documentation that is only used on the website. 99be691f3bSpatrick# Without this we will get a lot of warnings about doc pages that aren't 100be691f3bSpatrick# included by any doctree (as the manpage ignores those pages but they are 101be691f3bSpatrick# potentially still around from a previous website generation). 102be691f3bSpatrickif building_man_page: 103be691f3bSpatrick exclude_patterns.append(automodapi_toctreedirnm) 104be691f3bSpatrick# Use the recommended 'any' rule so that referencing SB API classes is possible 105be691f3bSpatrick# by just writing `SBData`. 106be691f3bSpatrickdefault_role = 'any' 107061da546Spatrick 108061da546Spatrick# If true, '()' will be appended to :func: etc. cross-reference text. 109061da546Spatrick#add_function_parentheses = True 110061da546Spatrick 111061da546Spatrick# If true, the current module name will be prepended to all description 112061da546Spatrick# unit titles (such as .. function::). 113061da546Spatrick#add_module_names = True 114061da546Spatrick 115061da546Spatrick# If true, sectionauthor and moduleauthor directives will be shown in the 116061da546Spatrick# output. They are ignored by default. 117061da546Spatrick#show_authors = False 118061da546Spatrick 119061da546Spatrick# The name of the Pygments (syntax highlighting) style to use. 120061da546Spatrickpygments_style = 'friendly' 121061da546Spatrick 122061da546Spatrick# A list of ignored prefixes for module index sorting. 123061da546Spatrick#modindex_common_prefix = [] 124061da546Spatrick 125061da546Spatrick 126061da546Spatrick# -- Options for HTML output --------------------------------------------------- 127061da546Spatrick 128061da546Spatrick# The theme to use for HTML and HTML Help pages. See the documentation for 129061da546Spatrick# a list of builtin themes. 130061da546Spatrickhtml_theme = 'alabaster' 131061da546Spatrick 132061da546Spatrick# Theme options are theme-specific and customize the look and feel of a theme 133061da546Spatrick# further. For a list of options available for each theme, see the 134061da546Spatrick# documentation. 135061da546Spatrickhtml_theme_options = { 136be691f3bSpatrick 'font_size': '11pt', 137be691f3bSpatrick # Don't generate any links to GitHub. 138be691f3bSpatrick 'github_button' : 'false', 139061da546Spatrick} 140061da546Spatrick 141061da546Spatrick# Add any paths that contain custom themes here, relative to this directory. 142061da546Spatrick#html_theme_path = [] 143061da546Spatrick 144061da546Spatrick# The name for this set of Sphinx documents. If None, it defaults to 145061da546Spatrick# "<project> v<release> documentation". 146061da546Spatrickhtml_title = 'The LLDB Debugger' 147061da546Spatrick 148061da546Spatrick# A shorter title for the navigation bar. Default is the same as html_title. 149061da546Spatrick#html_short_title = None 150061da546Spatrick 151061da546Spatrick# The name of an image file (relative to this directory) to place at the top 152061da546Spatrick# of the sidebar. 153061da546Spatrick#html_logo = None 154061da546Spatrick 155061da546Spatrick# The name of an image file (within the static path) to use as favicon of the 156061da546Spatrick# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 157061da546Spatrick# pixels large. 158061da546Spatrick#html_favicon = None 159061da546Spatrick 160061da546Spatrick# Add any paths that contain custom static files (such as style sheets) here, 161061da546Spatrick# relative to this directory. They are copied after the builtin static files, 162061da546Spatrick# so a file named "default.css" will overwrite the builtin "default.css". 163061da546Spatrickhtml_static_path = ['_static'] 164061da546Spatrick 165061da546Spatrickhtml_context = { 166061da546Spatrick 'css_files': [ 167061da546Spatrick '_static/lldb.css' 168061da546Spatrick ], 169061da546Spatrick } 170061da546Spatrick 171061da546Spatrickhtml_extra_path = ['.htaccess'] 172061da546Spatrick 173061da546Spatrick# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 174061da546Spatrick# using the given strftime format. 175061da546Spatrickhtml_last_updated_fmt = '%b %d, %Y' 176061da546Spatrick 177061da546Spatrick# If true, SmartyPants will be used to convert quotes and dashes to 178061da546Spatrick# typographically correct entities. 179061da546Spatrick#html_use_smartypants = True 180061da546Spatrick 181061da546Spatrick# Custom sidebar templates, maps document names to template names. 182061da546Spatrick#html_sidebars = {} 183061da546Spatrick 184061da546Spatrick# Additional templates that should be rendered to pages, maps page names to 185061da546Spatrick# template names. 186061da546Spatrick#html_additional_pages = {} 187061da546Spatrick 188061da546Spatrick# If false, no module index is generated. 189061da546Spatrick#html_domain_indices = True 190061da546Spatrick 191061da546Spatrick# If false, no index is generated. 192061da546Spatrick#html_use_index = True 193061da546Spatrick 194061da546Spatrick# If true, the index is split into individual pages for each letter. 195061da546Spatrick#html_split_index = False 196061da546Spatrick 197061da546Spatrick# If true, links to the reST sources are added to the pages. 198061da546Spatrick#html_show_sourcelink = True 199061da546Spatrick 200061da546Spatrick# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 201061da546Spatrick#html_show_sphinx = True 202061da546Spatrick 203061da546Spatrick# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 204061da546Spatrick#html_show_copyright = True 205061da546Spatrick 206061da546Spatrick# If true, an OpenSearch description file will be output, and all pages will 207061da546Spatrick# contain a <link> tag referring to it. The value of this option must be the 208061da546Spatrick# base URL from which the finished HTML is served. 209061da546Spatrick#html_use_opensearch = '' 210061da546Spatrick 211061da546Spatrick# This is the file name suffix for HTML files (e.g. ".xhtml"). 212061da546Spatrick#html_file_suffix = None 213061da546Spatrick 214061da546Spatrick# Output file base name for HTML help builder. 215061da546Spatrickhtmlhelp_basename = 'LLDBdoc' 216061da546Spatrick 217061da546Spatrick# If true, the reST sources are included in the HTML build as 218061da546Spatrick# _sources/name. The default is True. 219061da546Spatrickhtml_copy_source = False 220061da546Spatrick 221061da546Spatrick# -- Options for LaTeX output -------------------------------------------------- 222061da546Spatrick 223061da546Spatricklatex_elements = { 224061da546Spatrick# The paper size ('letterpaper' or 'a4paper'). 225061da546Spatrick#'papersize': 'letterpaper', 226061da546Spatrick 227061da546Spatrick# The font size ('10pt', '11pt' or '12pt'). 228061da546Spatrick#'pointsize': '10pt', 229061da546Spatrick 230061da546Spatrick# Additional stuff for the LaTeX preamble. 231061da546Spatrick#'preamble': '', 232061da546Spatrick} 233061da546Spatrick 234061da546Spatrick# Grouping the document tree into LaTeX files. List of tuples 235061da546Spatrick# (source start file, target name, title, author, documentclass [howto/manual]). 236061da546Spatricklatex_documents = [ 237061da546Spatrick ('index', 'LLDB.tex', u'LLDB Documentation', 238061da546Spatrick u'The LLDB Team', 'manual'), 239061da546Spatrick] 240061da546Spatrick 241061da546Spatrick# The name of an image file (relative to this directory) to place at the top of 242061da546Spatrick# the title page. 243061da546Spatrick#latex_logo = None 244061da546Spatrick 245061da546Spatrick# For "manual" documents, if this is true, then toplevel headings are parts, 246061da546Spatrick# not chapters. 247061da546Spatrick#latex_use_parts = False 248061da546Spatrick 249061da546Spatrick# If true, show page references after internal links. 250061da546Spatrick#latex_show_pagerefs = False 251061da546Spatrick 252061da546Spatrick# If true, show URL addresses after external links. 253061da546Spatrick#latex_show_urls = False 254061da546Spatrick 255061da546Spatrick# Documents to append as an appendix to all manuals. 256061da546Spatrick#latex_appendices = [] 257061da546Spatrick 258061da546Spatrick# If false, no module index is generated. 259061da546Spatrick#latex_domain_indices = True 260061da546Spatrick 261061da546Spatrick 262061da546Spatrick# -- Options for manual page output -------------------------------------------- 263061da546Spatrick 264061da546Spatrick# One entry per manual page. List of tuples 265061da546Spatrick# (source start file, name, description, authors, manual section). 266be691f3bSpatrickman_pages = [('man/lldb', 'lldb', u'LLDB Documentation', [u'LLVM project'], 1), 267be691f3bSpatrick ('man/lldb-server', 'lldb-server', u'LLDB Documentation', [u'LLVM project'], 1), 268be691f3bSpatrick ] 269061da546Spatrick 270061da546Spatrick# If true, show URL addresses after external links. 271061da546Spatrick#man_show_urls = False 272061da546Spatrick 273061da546Spatrick# -- Options for Texinfo output ------------------------------------------------ 274061da546Spatrick 275061da546Spatrick# Grouping the document tree into Texinfo files. List of tuples 276061da546Spatrick# (source start file, target name, title, author, 277061da546Spatrick# dir menu entry, description, category) 278061da546Spatricktexinfo_documents = [ 279061da546Spatrick ('index', 'LLDB', u'LLDB Documentation', 280061da546Spatrick u'The LLDB Team', 'LLDB', 'One line description of project.', 281061da546Spatrick 'Miscellaneous'), 282061da546Spatrick] 283061da546Spatrick 284061da546Spatrick# Documents to append as an appendix to all manuals. 285061da546Spatrick#texinfo_appendices = [] 286061da546Spatrick 287061da546Spatrick# If false, no module index is generated. 288061da546Spatrick#texinfo_domain_indices = True 289061da546Spatrick 290061da546Spatrick# How to display URL addresses: 'footnote', 'no', or 'inline'. 291061da546Spatrick#texinfo_show_urls = 'footnote' 292be691f3bSpatrick 293be691f3bSpatrickempty_attr_summary = re.compile(r'\.\. rubric:: Attributes Summary\s*\.\. autosummary::\s*\.\. rubric::') 294be691f3bSpatrickempty_attr_documentation = re.compile(r'\.\. rubric:: Attributes Documentation\s*\.\. rubric::') 295be691f3bSpatrick 296*f6aab3d8Srobertdef preprocess_source(app, docname, source): 297*f6aab3d8Srobert """ Preprocesses source files generated by automodapi. """ 298be691f3bSpatrick # Don't cleanup anything beside automodapi-generated sources. 299be691f3bSpatrick if not automodapi_toctreedirnm in docname: 300be691f3bSpatrick return 301be691f3bSpatrick processed = source[0] 302be691f3bSpatrick 303be691f3bSpatrick # Don't show the list of inheritance info as there is no inheritance in the 304be691f3bSpatrick # SBI API. This avoids all the repeated text on all doc pages that a 305be691f3bSpatrick # class inherits from 'object'. 306be691f3bSpatrick 307be691f3bSpatrick processed = processed.replace(":show-inheritance:", "") 308be691f3bSpatrick # Remove the SWIG generated 'thisown' attribute. It just bloats the generated 309be691f3bSpatrick # documentation and users shouldn't fiddle with the value anyway. 310be691f3bSpatrick processed = re.sub(r'~SB[a-zA-Z]+\.thisown', "", processed) 311be691f3bSpatrick processed = processed.replace(" .. autoattribute:: thisown", "") 312be691f3bSpatrick 313be691f3bSpatrick # After removing 'thisown', many objects don't have any attributes left. 314be691f3bSpatrick # Remove all now empty attribute summary/documentation sections with 315be691f3bSpatrick # some rather ugly regex. 316be691f3bSpatrick processed = empty_attr_summary.sub('.. rubric::', processed) 317be691f3bSpatrick processed = empty_attr_documentation.sub('.. rubric::', processed) 318be691f3bSpatrick 319be691f3bSpatrick # Replace the original source with the processed one (source is a single 320be691f3bSpatrick # element list). 321be691f3bSpatrick source[0] = processed 322be691f3bSpatrick 323*f6aab3d8Srobertdef cleanup_source(app, exception): 324*f6aab3d8Srobert """ Remove files generated by automodapi in the source tree. """ 325*f6aab3d8Srobert if hasattr(app.config, 'automodapi_toctreedirnm'): 326*f6aab3d8Srobert api_source_dir = os.path.join(app.srcdir, app.config.automodapi_toctreedirnm) 327*f6aab3d8Srobert shutil.rmtree(api_source_dir, ignore_errors=True) 328*f6aab3d8Srobert 329be691f3bSpatrickdef setup(app): 330*f6aab3d8Srobert app.connect('source-read', preprocess_source) 331*f6aab3d8Srobert app.connect('build-finished', cleanup_source) 332