mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
4dbb62b9cd
Via a new configuration verbatimradius of 'sphinxsetup', which defaults to 0pt. If this dimension is non zero, the LaTeX package pict2e will be loaded to help construct frames with rounded corners for code-blocks. And if the LaTeX package pict2e was not found, a LaTeX warning is issued during PDF build.
192 lines
6.9 KiB
Python
192 lines
6.9 KiB
Python
# Sphinx documentation build configuration file
|
|
|
|
import os
|
|
import re
|
|
|
|
import sphinx
|
|
|
|
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
|
|
'sphinx.ext.autosummary', 'sphinx.ext.extlinks',
|
|
'sphinx.ext.intersphinx',
|
|
'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram']
|
|
|
|
root_doc = 'contents'
|
|
templates_path = ['_templates']
|
|
exclude_patterns = ['_build']
|
|
|
|
project = 'Sphinx'
|
|
copyright = '2007-2022, Georg Brandl and the Sphinx team'
|
|
version = sphinx.__display_version__
|
|
release = version
|
|
show_authors = True
|
|
|
|
html_theme = 'sphinx13'
|
|
html_theme_path = ['_themes']
|
|
modindex_common_prefix = ['sphinx.']
|
|
html_static_path = ['_static']
|
|
html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
|
|
html_title = 'Sphinx documentation'
|
|
html_additional_pages = {'index': 'index.html'}
|
|
html_use_opensearch = 'https://www.sphinx-doc.org/en/master'
|
|
html_baseurl = 'https://www.sphinx-doc.org/en/master/'
|
|
html_favicon = '_static/favicon.svg'
|
|
|
|
htmlhelp_basename = 'Sphinxdoc'
|
|
|
|
epub_theme = 'epub'
|
|
epub_basename = 'sphinx'
|
|
epub_author = 'Georg Brandl'
|
|
epub_publisher = 'https://www.sphinx-doc.org/'
|
|
epub_uid = 'web-site'
|
|
epub_scheme = 'url'
|
|
epub_identifier = epub_publisher
|
|
epub_pre_files = [('index.xhtml', 'Welcome')]
|
|
epub_post_files = [('usage/installation.xhtml', 'Installing Sphinx'),
|
|
('develop.xhtml', 'Sphinx development')]
|
|
epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
|
|
'_static/jquery.js', '_static/searchtools.js',
|
|
'_static/underscore.js', '_static/basic.css',
|
|
'_static/language_data.js',
|
|
'search.html', '_static/websupport.js']
|
|
epub_fix_images = False
|
|
epub_max_image_width = 0
|
|
epub_show_urls = 'inline'
|
|
epub_use_index = False
|
|
epub_guide = (('toc', 'contents.xhtml', 'Table of Contents'),)
|
|
epub_description = 'Sphinx documentation generator system manual'
|
|
|
|
latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
|
|
'Georg Brandl', 'manual', 1)]
|
|
latex_logo = '_static/sphinx.png'
|
|
latex_elements = {
|
|
'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}',
|
|
'passoptionstopackages': r'''
|
|
\PassOptionsToPackage{svgnames}{xcolor}
|
|
''',
|
|
'preamble': r'''
|
|
\DeclareUnicodeCharacter{229E}{\ensuremath{\boxplus}}
|
|
\setcounter{tocdepth}{3}% depth of what main TOC shows (3=subsubsection)
|
|
\setcounter{secnumdepth}{1}% depth of section numbering
|
|
''',
|
|
# fix missing index entry due to RTD doing only once pdflatex after makeindex
|
|
'printindex': r'''
|
|
\IfFileExists{\jobname.ind}
|
|
{\footnotesize\raggedright\printindex}
|
|
{\begin{sphinxtheindex}\end{sphinxtheindex}}
|
|
''',
|
|
'sphinxsetup': """%
|
|
VerbatimColor={RGB}{242,242,242},%
|
|
VerbatimBorderColor={RGB}{32,32,32},%
|
|
verbatimradius=3pt%
|
|
""",
|
|
}
|
|
latex_show_urls = 'footnote'
|
|
latex_use_xindy = True
|
|
|
|
autodoc_member_order = 'groupwise'
|
|
autosummary_generate = False
|
|
todo_include_todos = True
|
|
extlinks = {'duref': ('https://docutils.sourceforge.io/docs/ref/rst/'
|
|
'restructuredtext.html#%s', '%s'),
|
|
'durole': ('https://docutils.sourceforge.io/docs/ref/rst/'
|
|
'roles.html#%s', '%s'),
|
|
'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/'
|
|
'directives.html#%s', '%s')}
|
|
|
|
man_pages = [
|
|
('contents', 'sphinx-all', 'Sphinx documentation generator system manual',
|
|
'Georg Brandl', 1),
|
|
('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool',
|
|
'', 1),
|
|
('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
|
|
'template generator', '', 1),
|
|
('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool',
|
|
'', 1),
|
|
('man/sphinx-autogen', 'sphinx-autogen', 'Generate autodoc stub pages',
|
|
'', 1),
|
|
]
|
|
|
|
texinfo_documents = [
|
|
('contents', 'sphinx', 'Sphinx Documentation', 'Georg Brandl',
|
|
'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools',
|
|
1),
|
|
]
|
|
|
|
intersphinx_mapping = {
|
|
'python': ('https://docs.python.org/3/', None),
|
|
'requests': ('https://requests.readthedocs.io/en/latest/', None),
|
|
'readthedocs': ('https://docs.readthedocs.io/en/stable', None),
|
|
}
|
|
|
|
# Sphinx document translation with sphinx gettext feature uses these settings:
|
|
locale_dirs = ['locale/']
|
|
gettext_compact = False
|
|
|
|
|
|
# -- Extension interface -------------------------------------------------------
|
|
|
|
from sphinx import addnodes # noqa
|
|
|
|
event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
|
|
|
|
|
|
def parse_event(env, sig, signode):
|
|
m = event_sig_re.match(sig)
|
|
if not m:
|
|
signode += addnodes.desc_name(sig, sig)
|
|
return sig
|
|
name, args = m.groups()
|
|
signode += addnodes.desc_name(name, name)
|
|
plist = addnodes.desc_parameterlist()
|
|
for arg in args.split(','):
|
|
arg = arg.strip()
|
|
plist += addnodes.desc_parameter(arg, arg)
|
|
signode += plist
|
|
return name
|
|
|
|
|
|
def linkify_issues_in_changelog(app, docname, source):
|
|
""" Linkify issue references like #123 in changelog to GitHub. """
|
|
|
|
if docname == 'changes':
|
|
changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES")
|
|
# this path trickery is needed because this script can
|
|
# be invoked with different working directories:
|
|
# * running make in docs/
|
|
# * running tox -e docs in the repo root dir
|
|
|
|
with open(changelog_path, encoding="utf-8") as f:
|
|
changelog = f.read()
|
|
|
|
def linkify(match):
|
|
url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1]
|
|
return '`{} <{}>`_'.format(match[0], url)
|
|
|
|
linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, changelog)
|
|
|
|
source[0] = source[0].replace('.. include:: ../CHANGES', linkified_changelog)
|
|
|
|
|
|
def setup(app):
|
|
from sphinx.ext.autodoc import cut_lines
|
|
from sphinx.util.docfields import GroupedField
|
|
app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
|
|
app.connect('source-read', linkify_issues_in_changelog)
|
|
app.add_object_type('confval', 'confval',
|
|
objname='configuration value',
|
|
indextemplate='pair: %s; configuration value')
|
|
app.add_object_type('setuptools-confval', 'setuptools-confval',
|
|
objname='setuptools configuration value',
|
|
indextemplate='pair: %s; setuptools configuration value')
|
|
fdesc = GroupedField('parameter', label='Parameters',
|
|
names=['param'], can_collapse=True)
|
|
app.add_object_type('event', 'event', 'pair: %s; event', parse_event,
|
|
doc_field_types=[fdesc])
|
|
|
|
# workaround for RTD
|
|
from sphinx.util import logging
|
|
logger = logging.getLogger(__name__)
|
|
app.info = lambda *args, **kwargs: logger.info(*args, **kwargs)
|
|
app.warn = lambda *args, **kwargs: logger.warning(*args, **kwargs)
|
|
app.debug = lambda *args, **kwargs: logger.debug(*args, **kwargs)
|