mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge branch 'master' into 5216-update-markdown-doc
This commit is contained in:
Timotheus Kampik
2
doc/_static/conf.py.txt
vendored
2
doc/_static/conf.py.txt
vendored
@@ -1,5 +1,3 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# test documentation build configuration file, created by
|
||||
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
|
||||
#
|
||||
|
||||
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 39 KiB After Width: | Height: | Size: 39 KiB |
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 56 KiB |
|
Before Width: | Height: | Size: 39 KiB After Width: | Height: | Size: 39 KiB |
|
Before Width: | Height: | Size: 73 KiB After Width: | Height: | Size: 73 KiB |
|
Before Width: | Height: | Size: 71 KiB After Width: | Height: | Size: 71 KiB |
|
Before Width: | Height: | Size: 82 KiB After Width: | Height: | Size: 82 KiB |
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 100 KiB After Width: | Height: | Size: 100 KiB |
|
Before Width: | Height: | Size: 86 KiB After Width: | Height: | Size: 86 KiB |
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 82 KiB After Width: | Height: | Size: 82 KiB |
|
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 90 KiB |
|
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 42 KiB |
|
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 27 KiB After Width: | Height: | Size: 27 KiB |
|
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 30 KiB |
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 14 KiB After Width: | Height: | Size: 14 KiB |
24
doc/conf.py
24
doc/conf.py
@@ -1,5 +1,3 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# Sphinx documentation build configuration file
|
||||
|
||||
import re
|
||||
@@ -44,6 +42,7 @@ epub_post_files = [('usage/installation.xhtml', 'Installing Sphinx'),
|
||||
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
|
||||
@@ -56,15 +55,27 @@ 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}',
|
||||
'fontpkg': r'''
|
||||
\usepackage[sc]{mathpazo}
|
||||
\usepackage[scaled]{helvet}
|
||||
\usepackage{courier}
|
||||
\substitutefont{LGR}{\rmdefault}{cmr}
|
||||
\substitutefont{LGR}{\sfdefault}{cmss}
|
||||
\substitutefont{LGR}{\ttdefault}{cmtt}
|
||||
\substitutefont{X2}{\rmdefault}{cmr}
|
||||
\substitutefont{X2}{\sfdefault}{cmss}
|
||||
\substitutefont{X2}{\ttdefault}{cmtt}
|
||||
''',
|
||||
'passoptionstopackages': '\\PassOptionsToPackage{svgnames}{xcolor}',
|
||||
'preamble': '\\DeclareUnicodeCharacter{229E}{\\ensuremath{\\boxplus}}',
|
||||
'fvset': '\\fvset{fontsize=auto}',
|
||||
'printindex': '\\footnotesize\\raggedright\\sphinxprintindex',
|
||||
# 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}}
|
||||
''',
|
||||
}
|
||||
latex_show_urls = 'footnote'
|
||||
latex_use_xindy = True
|
||||
@@ -139,3 +150,10 @@ def setup(app):
|
||||
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)
|
||||
|
||||
@@ -14,16 +14,17 @@ Sphinx documentation contents
|
||||
usage/configuration
|
||||
usage/builders/index
|
||||
usage/extensions/index
|
||||
usage/theming
|
||||
usage/advanced/intl
|
||||
usage/advanced/setuptools
|
||||
usage/advanced/websupport/index
|
||||
|
||||
intro
|
||||
man/index
|
||||
intl
|
||||
theming
|
||||
setuptools
|
||||
templating
|
||||
latex
|
||||
extdev/index
|
||||
websupport
|
||||
|
||||
faq
|
||||
glossary
|
||||
|
||||
@@ -127,7 +127,7 @@ own extensions.
|
||||
.. _NumPy style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
|
||||
.. _hyphenator: https://github.com/mnater/hyphenator
|
||||
.. _exceltable: https://pythonhosted.org/sphinxcontrib-exceltable/
|
||||
.. _YouTube: http://www.youtube.com/
|
||||
.. _YouTube: https://www.youtube.com/
|
||||
.. _ClearQuest: https://www.ibm.com/us-en/marketplace/rational-clearquest
|
||||
.. _Zope interfaces: https://zopeinterface.readthedocs.io/en/latest/README.html
|
||||
.. _slideshare: https://www.slideshare.net/
|
||||
|
||||
@@ -115,37 +115,15 @@ Emitting events
|
||||
.. automethod:: emit_firstresult(event, \*arguments)
|
||||
|
||||
|
||||
Producing messages / logging
|
||||
----------------------------
|
||||
|
||||
The application object also provides support for emitting leveled messages.
|
||||
|
||||
.. note::
|
||||
|
||||
There is no "error" call: in Sphinx, errors are defined as things that stop
|
||||
the build; just raise an exception (:exc:`sphinx.errors.SphinxError` or a
|
||||
custom subclass) to do that.
|
||||
|
||||
.. deprecated:: 1.6
|
||||
|
||||
Please use :ref:`logging-api` instead.
|
||||
|
||||
.. automethod:: Sphinx.warn
|
||||
|
||||
.. automethod:: Sphinx.info
|
||||
|
||||
.. automethod:: Sphinx.verbose
|
||||
|
||||
.. automethod:: Sphinx.debug
|
||||
|
||||
.. automethod:: Sphinx.debug2
|
||||
|
||||
|
||||
Sphinx runtime information
|
||||
--------------------------
|
||||
|
||||
The application object also provides runtime information as attributes.
|
||||
|
||||
.. attribute:: Sphinx.project
|
||||
|
||||
Target project. See :class:`.Project`.
|
||||
|
||||
.. attribute:: Sphinx.srcdir
|
||||
|
||||
Source directory.
|
||||
|
||||
@@ -15,6 +15,10 @@ Build environment API
|
||||
|
||||
Reference to the :class:`.Config` object.
|
||||
|
||||
.. attribute:: project
|
||||
|
||||
Target project. See :class:`.Project`.
|
||||
|
||||
.. attribute:: srcdir
|
||||
|
||||
Source directory.
|
||||
@@ -39,10 +43,6 @@ Build environment API
|
||||
|
||||
**Utility methods**
|
||||
|
||||
.. automethod:: warn
|
||||
|
||||
.. automethod:: warn_node
|
||||
|
||||
.. automethod:: doc2path
|
||||
|
||||
.. automethod:: relfn2path
|
||||
|
||||
@@ -85,6 +85,7 @@ APIs used for writing extensions
|
||||
|
||||
tutorial
|
||||
appapi
|
||||
projectapi
|
||||
envapi
|
||||
builderapi
|
||||
collectorapi
|
||||
@@ -96,6 +97,8 @@ APIs used for writing extensions
|
||||
i18n
|
||||
utils
|
||||
|
||||
.. _dev-deprecated-apis:
|
||||
|
||||
Deprecated APIs
|
||||
---------------
|
||||
|
||||
@@ -104,7 +107,13 @@ But, sometimes, the change of interface are needed for some reasons. In such
|
||||
cases, we've marked them as deprecated. And they are kept during the two
|
||||
major versions (for more details, please see :ref:`deprecation-policy`).
|
||||
|
||||
The following is a list of deprecated interface.
|
||||
The following is a list of deprecated interfaces.
|
||||
|
||||
.. tabularcolumns:: |>{\raggedright}\Y{.4}|>{\centering}\Y{.1}|>{\centering}\Y{.12}|>{\raggedright\arraybackslash}\Y{.38}|
|
||||
|
||||
.. |LaTeXHyphenate| raw:: latex
|
||||
|
||||
\hspace{0pt}
|
||||
|
||||
.. list-table:: deprecated APIs
|
||||
:header-rows: 1
|
||||
@@ -112,10 +121,230 @@ The following is a list of deprecated interface.
|
||||
:widths: 40, 10, 10, 40
|
||||
|
||||
* - Target
|
||||
- Deprecated
|
||||
- (will be) Removed
|
||||
- |LaTeXHyphenate|\ Deprecated
|
||||
- (will be) Removed
|
||||
- Alternatives
|
||||
|
||||
* - ``encoding`` argument of ``autodoc.Documenter.get_doc()``,
|
||||
``autodoc.DocstringSignatureMixin.get_doc()``,
|
||||
``autodoc.DocstringSignatureMixin._find_signature()``, and
|
||||
``autodoc.ClassDocumenter.get_doc()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``nodetype`` argument of
|
||||
``sphinx.search.WordCollector.is_meta_keywords()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``suffix`` argument of ``BuildEnvironment.doc2path()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - string style ``base`` argument of ``BuildEnvironment.doc2path()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``os.path.join()``
|
||||
|
||||
* - ``sphinx.addnodes.abbreviation``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``docutils.nodes.abbreviation``
|
||||
|
||||
* - ``sphinx.cmd.quickstart.term_decode()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.cmd.quickstart.TERM_ENCODING``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``sys.stdin.encoding``
|
||||
|
||||
* - ``sphinx.config.check_unicode()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.config.string_classes``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``[str]``
|
||||
|
||||
* - ``sphinx.domains.cpp.DefinitionError.description``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``str(exc)``
|
||||
|
||||
* - ``sphinx.domains.cpp.NoOldIdError.description``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``str(exc)``
|
||||
|
||||
* - ``sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``str(exc)``
|
||||
|
||||
* - ``sphinx.ext.autosummary.Autosummary.warn()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.ext.autosummary.Autosummary.genopt``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.ext.autosummary.Autosummary.warnings``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.ext.autosummary.Autosummary.result``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.ext.doctest.doctest_encode()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.testing.util.remove_unicode_literal()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.util.attrdict``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.util.force_decode()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.util.get_matching_docs()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``sphinx.util.get_matching_files()``
|
||||
|
||||
* - ``sphinx.util.inspect.Parameter``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.util.osutil.EEXIST``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``errno.EEXIST`` or ``FileExistsError``
|
||||
|
||||
* - ``sphinx.util.osutil.EINVAL``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``errno.EINVAL``
|
||||
|
||||
* - ``sphinx.util.osutil.ENOENT``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``errno.ENOENT`` or ``FileNotFoundError``
|
||||
|
||||
* - ``sphinx.util.osutil.EPIPE``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``errno.ENOENT`` or ``BrokenPipeError``
|
||||
|
||||
* - ``sphinx.util.osutil.walk()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``os.walk()``
|
||||
|
||||
* - ``sphinx.util.pycompat.UnicodeMixin``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.util.pycompat.u``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.util.PeekableIterator``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - Omitting the ``filename`` argument in an overriddent
|
||||
``IndexBuilder.feed()`` method.
|
||||
- 2.0
|
||||
- 4.0
|
||||
- ``IndexBuilder.feed(docname, filename, title, doctree)``
|
||||
|
||||
* - ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.application.Sphinx._setting_up_extension``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - The ``importer`` argument of ``sphinx.ext.autodoc.importer._MockModule``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.ext.autodoc.importer._MockImporter``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.io.SphinxBaseFileInput``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.io.SphinxFileInput.supported``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.io.SphinxRSTFileInput``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.registry.SphinxComponentRegistry.add_source_input()``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.latex.LaTeXTranslator.collect_footnotes()``
|
||||
- 2.0
|
||||
- 4.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.text.TextTranslator._make_depart_admonition()``
|
||||
- 2.0
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - :rst:dir:`highlightlang`
|
||||
- 1.8
|
||||
- 4.0
|
||||
@@ -131,11 +360,68 @@ The following is a list of deprecated interface.
|
||||
- 4.0
|
||||
- :meth:`~sphinx.application.Sphinx.add_js_file()`
|
||||
|
||||
* - :confval:`autodoc_default_flags`
|
||||
- 1.8
|
||||
- 4.0
|
||||
- :confval:`autodoc_default_options`
|
||||
|
||||
* - ``content`` arguments of ``sphinx.util.image.guess_mimetype()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``gettext_compact`` arguments of
|
||||
``sphinx.util.i18n.find_catalog_source_files()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.io.SphinxI18nReader.set_lineno_for_reporter()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.io.SphinxI18nReader.line``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.directives.other.VersionChanges``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``sphinx.domains.changeset.VersionChanges``
|
||||
|
||||
* - ``sphinx.highlighting.PygmentsBridge.unhighlight()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``trim_doctest_flags`` arguments of
|
||||
``sphinx.highlighting.PygmentsBridge``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.ext.mathbase``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.ext.mathbase.MathDomain``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``sphinx.domains.math.MathDomain``
|
||||
|
||||
* - ``sphinx.ext.mathbase.MathDirective``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``sphinx.directives.patches.MathDirective``
|
||||
|
||||
* - ``sphinx.ext.mathbase.math_role()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``docutils.parsers.rst.roles.math_role()``
|
||||
|
||||
* - ``sphinx.ext.mathbase.setup_math()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
@@ -146,6 +432,16 @@ The following is a list of deprecated interface.
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.ext.mathbase.get_node_equation_number()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``sphinx.util.math.get_node_equation_number()``
|
||||
|
||||
* - ``sphinx.ext.mathbase.wrap_displaymath()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``sphinx.util.math.wrap_displaymath()``
|
||||
|
||||
* - ``sphinx.ext.mathbase.math`` (node)
|
||||
- 1.8
|
||||
- 3.0
|
||||
@@ -221,11 +517,61 @@ The following is a list of deprecated interface.
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.latex.LaTeXTranslator.hlsettingstack``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.latex.ExtBabel.get_shorthandoff()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.html.HTMLTranslator.highlightlang()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.html.HTMLTranslator.highlightlang_base()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.html.HTMLTranslator.highlightlangopts()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.html.HTMLTranslator.highlightlinenothreshold()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.html5.HTMLTranslator.highlightlang()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.html5.HTMLTranslator.highlightlang_base()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.html5.HTMLTranslator.highlightlangopts()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.writers.latex.LaTeXTranslator.check_latex_elements()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- Nothing
|
||||
|
||||
* - ``sphinx.application.CONFIG_FILENAME``
|
||||
- 1.8
|
||||
- 3.0
|
||||
@@ -309,6 +655,11 @@ The following is a list of deprecated interface.
|
||||
- 3.0
|
||||
- :confval:`nitpick_ignore`
|
||||
|
||||
* - ``BuildEnvironment.versionchanges``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- N/A
|
||||
|
||||
* - ``BuildEnvironment.update()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
@@ -334,6 +685,11 @@ The following is a list of deprecated interface.
|
||||
- 3.0
|
||||
- ``Builder.write_doctree()``
|
||||
|
||||
* - ``BuildEnvironment.note_versionchange()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``ChangesDomain.note_changeset()``
|
||||
|
||||
* - ``warn()`` (template helper function)
|
||||
- 1.8
|
||||
- 3.0
|
||||
@@ -354,6 +710,11 @@ The following is a list of deprecated interface.
|
||||
- 3.0
|
||||
- ``sphinx.cmd.build``
|
||||
|
||||
* - ``sphinx.make_mode``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``sphinx.cmd.make_mode``
|
||||
|
||||
* - ``sphinx.locale.l_()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
|
||||
@@ -9,9 +9,9 @@ Logging API
|
||||
|
||||
.. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter)
|
||||
|
||||
.. method:: SphinxLoggerAdapter.error(level, msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.critical(level, msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.warning(level, msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.error(msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.critical(msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.warning(msg, *args, **kwargs)
|
||||
|
||||
Logs a message on this logger with the specified level.
|
||||
Basically, the arguments are as with python's logging module.
|
||||
@@ -33,13 +33,14 @@ Logging API
|
||||
logger.warning('Warning happened!', location=some_node)
|
||||
|
||||
**color**
|
||||
The color of logs. By default, warning level logs are
|
||||
colored as ``"darkred"``. The others are not colored.
|
||||
The color of logs. By default, error level logs are colored as
|
||||
``"darkred"``, critical level ones is not colored, and warning level
|
||||
ones are colored as ``"red"``.
|
||||
|
||||
.. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.info(level, msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.verbose(level, msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.debug(level, msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.info(msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.verbose(msg, *args, **kwargs)
|
||||
.. method:: SphinxLoggerAdapter.debug(msg, *args, **kwargs)
|
||||
|
||||
Logs a message to this logger with the specified level.
|
||||
Basically, the arguments are as with python's logging module.
|
||||
@@ -55,10 +56,11 @@ Logging API
|
||||
:meth:`SphinxLoggerAdapter.warning`.
|
||||
|
||||
**color**
|
||||
The color of logs. By default, debug level logs are
|
||||
colored as ``"darkgray"``, and debug2 level ones are ``"lightgray"``.
|
||||
The others are not colored.
|
||||
The color of logs. By default, info and verbose level logs are not colored,
|
||||
and deug level ones are colored as ``"darkgray"``.
|
||||
|
||||
.. autofunction:: pending_logging()
|
||||
|
||||
.. autofunction:: pending_warnings()
|
||||
|
||||
.. autofunction:: prefixed_warnings()
|
||||
|
||||
9
doc/extdev/projectapi.rst
Normal file
9
doc/extdev/projectapi.rst
Normal file
@@ -0,0 +1,9 @@
|
||||
.. _project-api:
|
||||
|
||||
Project API
|
||||
===========
|
||||
|
||||
.. currentmodule:: sphinx.project
|
||||
|
||||
.. autoclass:: Project
|
||||
:members:
|
||||
@@ -20,7 +20,7 @@ How do I...
|
||||
the :rst:dir:`toctree` directive where you want to start numbering.
|
||||
|
||||
... customize the look of the built HTML files?
|
||||
Use themes, see :doc:`theming`.
|
||||
Use themes, see :doc:`/usage/theming`.
|
||||
|
||||
... add global substitutions or includes?
|
||||
Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value.
|
||||
@@ -205,7 +205,7 @@ The following list gives some hints for the creation of epub files:
|
||||
.. _Epubcheck: https://github.com/IDPF/epubcheck
|
||||
.. _Calibre: https://calibre-ebook.com/
|
||||
.. _FBreader: https://fbreader.org/
|
||||
.. _Bookworm: http://www.oreilly.com/bookworm/index.html
|
||||
.. _Bookworm: https://www.oreilly.com/bookworm/index.html
|
||||
.. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211
|
||||
|
||||
.. _texinfo-faq:
|
||||
|
||||
@@ -55,15 +55,13 @@ See the :ref:`pertinent section in the FAQ list <usingwith>`.
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Sphinx needs at least **Python 2.7** or **Python 3.4** to run, as well as the
|
||||
docutils_ and Jinja2_ libraries. Sphinx should work with docutils version 0.10
|
||||
or some (not broken) SVN trunk snapshot. If you like to have source code
|
||||
highlighting support, you must also install the Pygments_ library.
|
||||
Sphinx needs at least **Python 3.5** to run, as well as the docutils_ and
|
||||
Jinja2_ libraries. Sphinx should work with docutils version 0.12 or some (not
|
||||
broken) SVN trunk snapshot.
|
||||
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
.. _docutils: http://docutils.sourceforge.net/
|
||||
.. _Jinja2: http://jinja.pocoo.org/
|
||||
.. _Pygments: http://pygments.org/
|
||||
|
||||
|
||||
Usage
|
||||
|
||||
@@ -55,7 +55,7 @@ example::
|
||||
\setlength{\cftsecnumwidth}{1.25cm}
|
||||
''',
|
||||
'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
|
||||
'printindex': r'\footnotesize\raggedright\sphinxprintindex',
|
||||
'printindex': r'\footnotesize\raggedright\printindex',
|
||||
}
|
||||
latex_show_urls = 'footnote'
|
||||
|
||||
@@ -209,7 +209,7 @@ The available styling options
|
||||
the default changed from ``false`` to ``true``.
|
||||
|
||||
``verbatimcontinuedalign``, ``verbatimcontinuesalign``
|
||||
default ``c``. Horizontal position relative to the framed contents:
|
||||
default ``r``. Horizontal position relative to the framed contents:
|
||||
either ``l`` (left aligned), ``r`` (right aligned) or ``c`` (centered).
|
||||
|
||||
.. versionadded:: 1.7
|
||||
@@ -354,9 +354,9 @@ The available styling options
|
||||
``attentionBgColor``, ``dangerBgColor``,
|
||||
``errorBgColor``
|
||||
|
||||
.. |warningborders| replace:: ``warningBorder``, ``cautionBorder``,
|
||||
``attentionBorder``, ``dangerBorder``,
|
||||
``errorBorder``
|
||||
.. |warningborders| replace:: ``warningborder``, ``cautionborder``,
|
||||
``attentionborder``, ``dangerborder``,
|
||||
``errorborder``
|
||||
|
||||
LaTeX macros and environments
|
||||
-----------------------------
|
||||
@@ -365,6 +365,8 @@ Here are some macros from the package file :file:`sphinx.sty` and class files
|
||||
:file:`sphinxhowto.cls`, :file:`sphinxmanual.cls`, which have public names
|
||||
thus allowing redefinitions. Check the respective files for the defaults.
|
||||
|
||||
.. _latex-macros:
|
||||
|
||||
Macros
|
||||
~~~~~~
|
||||
|
||||
@@ -390,32 +392,34 @@ Macros
|
||||
.. versionadded:: 1.6.3
|
||||
``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``.
|
||||
- the table of contents is typeset via ``\sphinxtableofcontents`` which is a
|
||||
wrapper (whose definition can be found in :file:`sphinxhowto.cls` or in
|
||||
:file:`sphinxmanual.cls`) of standard ``\tableofcontents``.
|
||||
wrapper (defined differently in :file:`sphinxhowto.cls` and in
|
||||
:file:`sphinxmanual.cls`) of standard ``\tableofcontents``. The macro
|
||||
``\sphinxtableofcontentshook`` is executed during its expansion right before
|
||||
``\tableofcontents`` itself.
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
|
||||
- the ``\maketitle`` command is redefined by the class files
|
||||
:file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`.
|
||||
.. versionchanged:: 2.0
|
||||
hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly
|
||||
done during loading of ``'manual'`` docclass are now executed later via
|
||||
``\sphinxtableofcontentshook``. This macro is also executed by the
|
||||
``'howto'`` docclass, but defaults to empty with it.
|
||||
- a custom ``\sphinxmaketitle`` is defined in the class files
|
||||
:file:`sphinxmanual.cls` and :file:`sphinxhowto.cls` and is used as
|
||||
default setting of ``'maketitle'`` :confval:`latex_elements` key.
|
||||
|
||||
.. versionchanged:: 1.8.3
|
||||
formerly, ``\maketitle`` from LaTeX document class was modified by
|
||||
Sphinx.
|
||||
- for ``'manual'`` docclass a macro ``\sphinxbackoftitlepage``, if it is
|
||||
defined, gets executed at end of ``\sphinxmaketitle``, before the final
|
||||
``\clearpage``. Use either the ``'maketitle'`` key or the ``'preamble'`` key
|
||||
of :confval:`latex_elements` to add a custom definition of
|
||||
``\sphinxbackoftitlepage``.
|
||||
|
||||
.. versionadded:: 1.8.3
|
||||
- the citation reference is typeset via ``\sphinxcite`` which is a wrapper
|
||||
of standard ``\cite``.
|
||||
- regarding the general index, the :confval:`latex_elements` dictionary has a
|
||||
``'printindex'`` key which defaults to ``'\\sphinxprintindex'``. It often
|
||||
proves advantageous to use::
|
||||
|
||||
'printindex': '\\footnotesize\\raggedright\\sphinxprintindex',
|
||||
|
||||
especially if the index contains long entries. The LaTeX class for Japanese
|
||||
``'manual'``-type documents already does the font size and text
|
||||
justification change, so the above is not needed then.
|
||||
|
||||
.. tip::
|
||||
|
||||
Advanced LaTeX users can also, via :confval:`latex_additional_files`, use
|
||||
a custom :program:`makeindex` style file :file:`python.ist`, or a custom
|
||||
:program:`xindy` style file :file:`sphinx.xdy` (see
|
||||
:confval:`latex_use_xindy`) in order to modify how the general index is
|
||||
typeset.
|
||||
|
||||
Environments
|
||||
~~~~~~~~~~~~
|
||||
@@ -470,8 +474,7 @@ Environments
|
||||
- the bibliography uses ``sphinxthebibliography`` and the Python Module index
|
||||
as well as the general index both use ``sphinxtheindex``; these environments
|
||||
are wrappers of the ``thebibliography`` and respectively ``theindex``
|
||||
environments, needed mainly to insert a corresponding entry in the PDF
|
||||
bookmarks and table of contents.
|
||||
environments as provided by the document class (or packages).
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
formerly, the original environments were modified by Sphinx.
|
||||
|
||||
@@ -58,6 +58,10 @@ Options
|
||||
|
||||
Maximum depth for the generated table of contents file.
|
||||
|
||||
.. option:: --tocfile
|
||||
|
||||
Filename for a table of contents file. Defaults to ``modules``.
|
||||
|
||||
.. option:: -T, --no-toc
|
||||
|
||||
Do not create a table of contents file. Ignored when :option:`--full` is
|
||||
|
||||
@@ -229,6 +229,13 @@ Options
|
||||
Turn warnings into errors. This means that the build stops at the first
|
||||
warning and ``sphinx-build`` exits with exit status 1.
|
||||
|
||||
.. option:: --keep-going
|
||||
|
||||
With -W option, keep going processing when getting warnings to the end
|
||||
of build, and ``sphinx-build`` exits with exit status 1.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
.. option:: -T
|
||||
|
||||
Display the full traceback when an unhandled exception occurs. Otherwise,
|
||||
@@ -273,7 +280,16 @@ variables to customize behavior:
|
||||
|
||||
.. describe:: PAPER
|
||||
|
||||
The value for '"papersize"` key of :confval:`latex_elements`.
|
||||
This sets the ``'papersize'`` key of :confval:`latex_elements`:
|
||||
i.e. ``PAPER=a4`` sets it to ``'a4paper'`` and ``PAPER=letter`` to
|
||||
``'letterpaper'``.
|
||||
|
||||
.. note::
|
||||
|
||||
Usage of this environment variable got broken at Sphinx 1.5 as
|
||||
``a4`` or ``letter`` ended up as option to LaTeX document in
|
||||
place of the needed ``a4paper``, resp. ``letterpaper``. Fixed at
|
||||
1.7.7.
|
||||
|
||||
.. describe:: SPHINXBUILD
|
||||
|
||||
|
||||
@@ -200,6 +200,10 @@ Overriding works like this::
|
||||
|
||||
{% set script_files = script_files + ["_static/myscript.js"] %}
|
||||
|
||||
.. deprecated:: 1.8.0
|
||||
|
||||
Please use ``.Sphinx.add_js_file()`` instead.
|
||||
|
||||
Helper Functions
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
319
doc/theming.rst
319
doc/theming.rst
@@ -5,6 +5,12 @@ HTML theming support
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
.. note::
|
||||
|
||||
This document provides information about creating your own theme. If you
|
||||
simply wish to use a pre-existing HTML themes, refer to
|
||||
:doc:`/usage/theming`.
|
||||
|
||||
Sphinx supports changing the appearance of its HTML output via *themes*. A
|
||||
theme is a collection of HTML templates, stylesheet(s) and other static files.
|
||||
Additionally, it has a configuration file which specifies from which theme to
|
||||
@@ -15,265 +21,13 @@ Themes are meant to be project-unaware, so they can be used for different
|
||||
projects without change.
|
||||
|
||||
|
||||
Using a theme
|
||||
-------------
|
||||
|
||||
Using an existing theme is easy. If the theme is builtin to Sphinx, you only
|
||||
need to set the :confval:`html_theme` config value. With the
|
||||
:confval:`html_theme_options` config value you can set theme-specific options
|
||||
that change the look and feel. For example, you could have the following in
|
||||
your :file:`conf.py`::
|
||||
|
||||
html_theme = "classic"
|
||||
html_theme_options = {
|
||||
"rightsidebar": "true",
|
||||
"relbarbgcolor": "black"
|
||||
}
|
||||
|
||||
That would give you the classic theme, but with a sidebar on the right side and
|
||||
a black background for the relation bar (the bar with the navigation links at
|
||||
the page's top and bottom).
|
||||
|
||||
If the theme does not come with Sphinx, it can be in two static forms: either a
|
||||
directory (containing :file:`theme.conf` and other needed files), or a zip file
|
||||
with the same contents. Either of them must be put where Sphinx can find it;
|
||||
for this there is the config value :confval:`html_theme_path`. It gives a list
|
||||
of directories, relative to the directory containing :file:`conf.py`, that can
|
||||
contain theme directories or zip files. For example, if you have a theme in the
|
||||
file :file:`blue.zip`, you can put it right in the directory containing
|
||||
:file:`conf.py` and use this configuration::
|
||||
|
||||
html_theme = "blue"
|
||||
html_theme_path = ["."]
|
||||
|
||||
The third form is a python package. If a theme you want to use is distributed
|
||||
as a python package, you can use it after installing
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# installing theme package
|
||||
$ pip install sphinxjp.themes.dotted
|
||||
|
||||
# use it in your conf.py
|
||||
html_theme = "dotted"
|
||||
|
||||
|
||||
.. _builtin-themes:
|
||||
|
||||
Builtin themes
|
||||
--------------
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |alabaster| | |classic| |
|
||||
| | |
|
||||
| *alabaster* | *classic* |
|
||||
+--------------------+--------------------+
|
||||
| |sphinxdoc| | |scrolls| |
|
||||
| | |
|
||||
| *sphinxdoc* | *scrolls* |
|
||||
+--------------------+--------------------+
|
||||
| |agogo| | |traditional| |
|
||||
| | |
|
||||
| *agogo* | *traditional* |
|
||||
+--------------------+--------------------+
|
||||
| |nature| | |haiku| |
|
||||
| | |
|
||||
| *nature* | *haiku* |
|
||||
+--------------------+--------------------+
|
||||
| |pyramid| | |bizstyle| |
|
||||
| | |
|
||||
| *pyramid* | *bizstyle* |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |alabaster| image:: themes/alabaster.png
|
||||
.. |classic| image:: themes/classic.png
|
||||
.. |sphinxdoc| image:: themes/sphinxdoc.png
|
||||
.. |scrolls| image:: themes/scrolls.png
|
||||
.. |agogo| image:: themes/agogo.png
|
||||
.. |traditional| image:: themes/traditional.png
|
||||
.. |nature| image:: themes/nature.png
|
||||
.. |haiku| image:: themes/haiku.png
|
||||
.. |pyramid| image:: themes/pyramid.png
|
||||
.. |bizstyle| image:: themes/bizstyle.png
|
||||
|
||||
Sphinx comes with a selection of themes to choose from.
|
||||
|
||||
.. cssclass:: clear
|
||||
|
||||
These themes are:
|
||||
|
||||
* **basic** -- This is a basically unstyled layout used as the base for the
|
||||
other themes, and usable as the base for custom themes as well. The HTML
|
||||
contains all important elements like sidebar and relation bar. There are
|
||||
these options (which are inherited by the other themes):
|
||||
|
||||
- **nosidebar** (true or false): Don't include the sidebar. Defaults to
|
||||
``False``.
|
||||
|
||||
- **sidebarwidth** (int or str): Width of the sidebar in pixels.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Defaults to 230 pixels.
|
||||
|
||||
- **body_min_width** (int or str): Minimal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 0 if you don't want
|
||||
a width limit. Defaults may depend on the theme (often 450px).
|
||||
|
||||
- **body_max_width** (int or str): Maximal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 'none' if you don't
|
||||
want a width limit. Defaults may depend on the theme (often 800px).
|
||||
|
||||
* **alabaster** -- `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
|
||||
(especially as used in his Requests project), which was itself originally based on
|
||||
@mitsuhiko's theme used for Flask & related projects.
|
||||
Check out at its `installation page`_ how to set up properly
|
||||
:confval:`html_sidebars` for its use.
|
||||
|
||||
.. _Alabaster theme: https://pypi.org/project/alabaster/
|
||||
.. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html
|
||||
|
||||
* **classic** -- This is the classic theme, which looks like `the Python 2
|
||||
documentation <https://docs.python.org/2/>`_. It can be customized via
|
||||
these options:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **stickysidebar** (true or false): Make the sidebar "fixed" so that it
|
||||
doesn't scroll out of view for long body content. This may not work well
|
||||
with all browsers. Defaults to ``False``.
|
||||
|
||||
- **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
|
||||
snippet that makes the sidebar collapsible via a button on its side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **externalrefs** (true or false): Display external links differently from
|
||||
internal links. Defaults to ``False``.
|
||||
|
||||
There are also various color and font options that can change the color scheme
|
||||
without having to write a custom stylesheet:
|
||||
|
||||
- **footerbgcolor** (CSS color): Background color for the footer line.
|
||||
- **footertextcolor** (CSS color): Text color for the footer line.
|
||||
- **sidebarbgcolor** (CSS color): Background color for the sidebar.
|
||||
- **sidebarbtncolor** (CSS color): Background color for the sidebar collapse
|
||||
button (used when *collapsiblesidebar* is ``True``).
|
||||
- **sidebartextcolor** (CSS color): Text color for the sidebar.
|
||||
- **sidebarlinkcolor** (CSS color): Link color for the sidebar.
|
||||
- **relbarbgcolor** (CSS color): Background color for the relation bar.
|
||||
- **relbartextcolor** (CSS color): Text color for the relation bar.
|
||||
- **relbarlinkcolor** (CSS color): Link color for the relation bar.
|
||||
- **bgcolor** (CSS color): Body background color.
|
||||
- **textcolor** (CSS color): Body text color.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **visitedlinkcolor** (CSS color): Body color for visited links.
|
||||
- **headbgcolor** (CSS color): Background color for headings.
|
||||
- **headtextcolor** (CSS color): Text color for headings.
|
||||
- **headlinkcolor** (CSS color): Link color for headings.
|
||||
- **codebgcolor** (CSS color): Background color for code blocks.
|
||||
- **codetextcolor** (CSS color): Default text color for code blocks, if not
|
||||
set differently by the highlighting style.
|
||||
|
||||
- **bodyfont** (CSS font-family): Font for normal text.
|
||||
- **headfont** (CSS font-family): Font for headings.
|
||||
|
||||
* **sphinxdoc** -- The theme originally used by this documentation. It features
|
||||
a sidebar on the right side. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
.. note::
|
||||
|
||||
The Sphinx documentation now uses
|
||||
`an adjusted version of the sphinxdoc theme
|
||||
<https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_.
|
||||
|
||||
* **scrolls** -- A more lightweight theme, based on `the Jinja documentation
|
||||
<http://jinja.pocoo.org/>`_. The following color options are available:
|
||||
|
||||
- **headerbordercolor**
|
||||
- **subheadlinecolor**
|
||||
- **linkcolor**
|
||||
- **visitedlinkcolor**
|
||||
- **admonitioncolor**
|
||||
|
||||
* **agogo** -- A theme created by Andi Albrecht. The following options are
|
||||
supported:
|
||||
|
||||
- **bodyfont** (CSS font family): Font for normal text.
|
||||
- **headerfont** (CSS font family): Font for headings.
|
||||
- **pagewidth** (CSS length): Width of the page content, default 70em.
|
||||
- **documentwidth** (CSS length): Width of the document (without sidebar),
|
||||
default 50em.
|
||||
- **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
|
||||
- **bgcolor** (CSS color): Background color.
|
||||
- **headerbg** (CSS value for "background"): background for the header area,
|
||||
default a grayish gradient.
|
||||
- **footerbg** (CSS value for "background"): background for the footer area,
|
||||
default a light gray gradient.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
|
||||
headings.
|
||||
- **headerlinkcolor** (CSS color): Color for the backreference link in
|
||||
headings.
|
||||
- **textalign** (CSS *text-align* value): Text alignment for the body, default
|
||||
is ``justify``.
|
||||
|
||||
* **nature** -- A greenish theme. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
* **pyramid** -- A theme from the Pyramid web framework project, designed by
|
||||
Blaise Laflamme. There are currently no options beyond *nosidebar* and
|
||||
*sidebarwidth*.
|
||||
|
||||
* **haiku** -- A theme without sidebar inspired by the `Haiku OS user guide
|
||||
<https://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following
|
||||
options are supported:
|
||||
|
||||
- **full_logo** (true or false, default ``False``): If this is true, the
|
||||
header will only show the :confval:`html_logo`. Use this for large logos.
|
||||
If this is false, the logo (if present) will be shown floating right, and
|
||||
the documentation title will be put in the header.
|
||||
- **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
|
||||
**hoverlinkcolor** (CSS colors): Colors for various body elements.
|
||||
|
||||
* **traditional** -- A theme resembling the old Python documentation. There are
|
||||
currently no options beyond *nosidebar* and *sidebarwidth*.
|
||||
|
||||
* **epub** -- A theme for the epub builder. This theme tries to save visual
|
||||
space which is a sparse resource on ebook readers. The following options
|
||||
are supported:
|
||||
|
||||
- **relbar1** (true or false, default ``True``): If this is true, the
|
||||
`relbar1` block is inserted in the epub output, otherwise it is omitted.
|
||||
- **footer** (true or false, default ``True``): If this is true, the
|
||||
`footer` block is inserted in the epub output, otherwise it is omitted.
|
||||
|
||||
- **bizstyle** -- A simple bluish theme. The following options are supported
|
||||
beyond *nosidebar* and *sidebarwidth*:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
|
||||
|
||||
.. versionchanged:: 1.3
|
||||
The 'default' theme has been renamed to 'classic'. 'default' is still
|
||||
available, however it will emit a notice that it is an alias for the new
|
||||
'alabaster' theme.
|
||||
|
||||
Creating themes
|
||||
---------------
|
||||
|
||||
As said, themes are either a directory or a zipfile (whose name is the theme
|
||||
name), containing the following:
|
||||
Themes take the form of either a directory or a zipfile (whose name is the
|
||||
theme name), containing the following:
|
||||
|
||||
* A :file:`theme.conf` file, see below.
|
||||
* A :file:`theme.conf` file.
|
||||
* HTML templates, if needed.
|
||||
* A ``static/`` directory containing any static files that will be copied to the
|
||||
output static directory on build. These can be images, styles, script files.
|
||||
@@ -295,7 +49,8 @@ Python :mod:`ConfigParser` module) and has the following structure:
|
||||
* The **inherit** setting gives the name of a "base theme", or ``none``. The
|
||||
base theme will be used to locate missing templates (most themes will not have
|
||||
to supply most templates if they use ``basic`` as the base theme), its options
|
||||
will be inherited, and all of its static files will be used as well.
|
||||
will be inherited, and all of its static files will be used as well. If you want
|
||||
to also inherit the stylesheet, include it via CSS' ``@import`` in your own.
|
||||
|
||||
* The **stylesheet** setting gives the name of a CSS file which will be
|
||||
referenced in the HTML header. If you need more than one CSS file, either
|
||||
@@ -318,16 +73,17 @@ Python :mod:`ConfigParser` module) and has the following structure:
|
||||
.. versionadded:: 1.7
|
||||
sidebar settings
|
||||
|
||||
|
||||
.. _distribute-your-theme:
|
||||
|
||||
Distribute your theme as a python package
|
||||
Distribute your theme as a Python package
|
||||
-----------------------------------------
|
||||
|
||||
As a way to distribute your theme, you can use python package. Python package
|
||||
As a way to distribute your theme, you can use Python package. Python package
|
||||
brings to users easy setting up ways.
|
||||
|
||||
To distribute your theme as a python package, please define an entry point
|
||||
called ``sphinx.html_themes`` in your setup.py file, and write a ``setup()``
|
||||
To distribute your theme as a Python package, please define an entry point
|
||||
called ``sphinx.html_themes`` in your ``setup.py`` file, and write a ``setup()``
|
||||
function to register your themes using ``add_html_theme()`` API in it::
|
||||
|
||||
# 'setup.py'
|
||||
@@ -347,9 +103,8 @@ function to register your themes using ``add_html_theme()`` API in it::
|
||||
def setup(app):
|
||||
app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
|
||||
|
||||
|
||||
If your theme package contains two or more themes, please call ``add_html_theme()``
|
||||
twice or more.
|
||||
If your theme package contains two or more themes, please call
|
||||
``add_html_theme()`` twice or more.
|
||||
|
||||
.. versionadded:: 1.2
|
||||
'sphinx_themes' entry_points feature.
|
||||
@@ -360,8 +115,9 @@ twice or more.
|
||||
.. versionadded:: 1.6
|
||||
``sphinx.html_themes`` entry_points feature.
|
||||
|
||||
|
||||
Templating
|
||||
~~~~~~~~~~
|
||||
----------
|
||||
|
||||
The :doc:`guide to templating <templating>` is helpful if you want to write your
|
||||
own templates. What is important to keep in mind is the order in which Sphinx
|
||||
@@ -376,7 +132,6 @@ name as an explicit directory: ``{% extends "basic/layout.html" %}``. From a
|
||||
user ``templates_path`` template, you can still use the "exclamation mark"
|
||||
syntax as described in the templating document.
|
||||
|
||||
|
||||
Static templates
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -393,40 +148,6 @@ templating to put the color options into the stylesheet. When a documentation
|
||||
is built with the classic theme, the output directory will contain a
|
||||
``_static/classic.css`` file where all template tags have been processed.
|
||||
|
||||
|
||||
.. [1] It is not an executable Python file, as opposed to :file:`conf.py`,
|
||||
because that would pose an unnecessary security risk if themes are
|
||||
shared.
|
||||
|
||||
Third Party Themes
|
||||
------------------
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |sphinx_rtd_theme| | |
|
||||
| | |
|
||||
| *sphinx_rtd_theme* | |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |sphinx_rtd_theme| image:: themes/sphinx_rtd_theme.png
|
||||
|
||||
* **sphinx_rtd_theme** -- `Read the Docs Sphinx Theme`_.
|
||||
This is a mobile-friendly sphinx theme that was made for readthedocs.org.
|
||||
View a working demo over on readthedocs.org. You can get install and options
|
||||
information at `Read the Docs Sphinx Theme`_ page.
|
||||
|
||||
.. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/
|
||||
|
||||
.. versionchanged:: 1.4
|
||||
**sphinx_rtd_theme** has become optional.
|
||||
|
||||
|
||||
Besides this, there are a lot of third party themes. You can find them on
|
||||
PyPI__, GitHub__, sphinx-themes.org__ and so on.
|
||||
|
||||
.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
|
||||
.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type=
|
||||
.. __: https://sphinx-themes.org/
|
||||
|
||||
@@ -9,7 +9,7 @@ Complementary to translations provided for Sphinx-generated messages such as
|
||||
navigation bars, Sphinx provides mechanisms facilitating *document* translations
|
||||
in itself. See the :ref:`intl-options` for details on configuration.
|
||||
|
||||
.. figure:: translation.png
|
||||
.. figure:: /_static/translation.png
|
||||
:width: 100%
|
||||
|
||||
Workflow visualization of translations in Sphinx. (The stick-figure is taken
|
||||
@@ -46,14 +46,14 @@ They can be delivered to translators which will transform them to ``.po`` files
|
||||
--- so called **message catalogs** --- containing a mapping from the original
|
||||
messages to foreign-language strings.
|
||||
|
||||
Gettext compiles them into a binary format known as **binary catalogs** through
|
||||
:program:`msgfmt` for efficiency reasons. If you make these files discoverable
|
||||
with :confval:`locale_dirs` for your :confval:`language`, Sphinx will pick them
|
||||
up automatically.
|
||||
*gettext* compiles them into a binary format known as **binary catalogs**
|
||||
through :program:`msgfmt` for efficiency reasons. If you make these files
|
||||
discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx
|
||||
will pick them up automatically.
|
||||
|
||||
An example: you have a document ``usage.rst`` in your Sphinx project. The
|
||||
gettext builder will put its messages into ``usage.pot``. Imagine you have
|
||||
Spanish translations [2]_ on your hands in ``usage.po`` --- for your builds to
|
||||
*gettext* builder will put its messages into ``usage.pot``. Imagine you have
|
||||
Spanish translations [2]_ stored in ``usage.po`` --- for your builds to
|
||||
be translated you need to follow these instructions:
|
||||
|
||||
* Compile your message catalog to a locale directory, say ``locale``, so it
|
||||
@@ -63,7 +63,8 @@ be translated you need to follow these instructions:
|
||||
msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
|
||||
|
||||
* Set :confval:`locale_dirs` to ``["locale/"]``.
|
||||
* Set :confval:`language` to ``es`` (also possible via :option:`-D <sphinx-build -D>`).
|
||||
* Set :confval:`language` to ``es`` (also possible via
|
||||
:option:`-D <sphinx-build -D>`).
|
||||
* Run your desired build.
|
||||
|
||||
|
||||
@@ -71,118 +72,124 @@ Translating with sphinx-intl
|
||||
----------------------------
|
||||
|
||||
Quick guide
|
||||
^^^^^^^^^^^
|
||||
~~~~~~~~~~~
|
||||
|
||||
`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.
|
||||
This section describe an easy way to translate with sphinx-intl.
|
||||
`sphinx-intl`_ is a useful tool to work with Sphinx translation flow. This
|
||||
section describe an easy way to translate with *sphinx-intl*.
|
||||
|
||||
#. Install `sphinx-intl`_ by :command:`pip install sphinx-intl` or
|
||||
:command:`easy_install sphinx-intl`.
|
||||
#. Install `sphinx-intl`_.
|
||||
|
||||
#. Add configurations to your `conf.py`::
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install sphinx-intl
|
||||
|
||||
#. Add configurations to ``conf.py``.
|
||||
|
||||
::
|
||||
|
||||
locale_dirs = ['locale/'] # path is example but recommended.
|
||||
gettext_compact = False # optional.
|
||||
|
||||
This case-study assumes that :confval:`locale_dirs` is set to 'locale/' and
|
||||
:confval:`gettext_compact` is set to `False` (the Sphinx document is
|
||||
This case-study assumes that :confval:`locale_dirs` is set to ``locale/`` and
|
||||
:confval:`gettext_compact` is set to ``False`` (the Sphinx document is
|
||||
already configured as such).
|
||||
|
||||
#. Extract document's translatable messages into pot files:
|
||||
#. Extract translatable messages into pot files.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make gettext
|
||||
|
||||
As a result, many pot files are generated under ``_build/gettext``
|
||||
directory.
|
||||
The generated pot files will be placed in the ``_build/gettext`` directory.
|
||||
|
||||
#. Setup/Update your `locale_dir`:
|
||||
#. Generate po files.
|
||||
|
||||
We'll use the pot files generated in the above step.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sphinx-intl update -p _build/gettext -l de -l ja
|
||||
|
||||
Done. You got these directories that contain po files:
|
||||
Once completed, the generated po files will be placed in the below
|
||||
directories:
|
||||
|
||||
* `./locale/de/LC_MESSAGES/`
|
||||
* `./locale/ja/LC_MESSAGES/`
|
||||
* ``./locale/de/LC_MESSAGES/``
|
||||
* ``./locale/ja/LC_MESSAGES/``
|
||||
|
||||
#. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
|
||||
#. Translate po files.
|
||||
|
||||
#. make translated document.
|
||||
AS noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
|
||||
directory. An example of one such file, from Sphinx, ``builders.po``, is
|
||||
given below.
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# a5600c3d2e3d48fc8c261ea0284db79b
|
||||
#: ../../builders.rst:4
|
||||
msgid "Available builders"
|
||||
msgstr "<FILL HERE BY TARGET LANGUAGE>"
|
||||
|
||||
Another case, msgid is multi-line text and contains reStructuredText syntax:
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# 302558364e1d41c69b3277277e34b184
|
||||
#: ../../builders.rst:9
|
||||
msgid ""
|
||||
"These are the built-in Sphinx builders. More builders can be added by "
|
||||
":ref:`extensions <extensions>`."
|
||||
msgstr ""
|
||||
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
|
||||
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
|
||||
|
||||
Please be careful not to break reST notation. Most po-editors will help you
|
||||
with that.
|
||||
|
||||
#. Build translated document.
|
||||
|
||||
You need a :confval:`language` parameter in ``conf.py`` or you may also
|
||||
specify the parameter on the command line (for BSD/GNU make):
|
||||
specify the parameter on the command line.
|
||||
|
||||
For for BSD/GNU make, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make -e SPHINXOPTS="-D language='de'" html
|
||||
|
||||
command line (for Windows cmd.exe):
|
||||
For Windows :command:`cmd.exe`, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
> set SPHINXOPTS=-D language=de
|
||||
> .\make.bat html
|
||||
|
||||
command line (for PowerShell):
|
||||
For PowerShell, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
> Set-Item env:SPHINXOPTS "-D language=de"
|
||||
> .\make.bat html
|
||||
|
||||
|
||||
Congratulations! You got the translated documentation in the ``_build/html``
|
||||
directory.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
sphinx-build that is invoked by make command will build po files into mo files.
|
||||
|
||||
If you are using 1.2.x or earlier, please invoke ``sphinx-intl build`` command
|
||||
before make command.
|
||||
:program:`sphinx-build` that is invoked by make command will build po files
|
||||
into mo files.
|
||||
|
||||
If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build`
|
||||
command before :command:`make` command.
|
||||
|
||||
Translating
|
||||
^^^^^^^^^^^
|
||||
|
||||
Translate po file under ``./locale/de/LC_MESSAGES`` directory.
|
||||
The case of builders.po file for sphinx document:
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# a5600c3d2e3d48fc8c261ea0284db79b
|
||||
#: ../../builders.rst:4
|
||||
msgid "Available builders"
|
||||
msgstr "<FILL HERE BY TARGET LANGUAGE>"
|
||||
|
||||
Another case, msgid is multi-line text and contains reStructuredText
|
||||
syntax:
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# 302558364e1d41c69b3277277e34b184
|
||||
#: ../../builders.rst:9
|
||||
msgid ""
|
||||
"These are the built-in Sphinx builders. More builders can be added by "
|
||||
":ref:`extensions <extensions>`."
|
||||
msgstr ""
|
||||
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
|
||||
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
|
||||
|
||||
Please be careful not to break reST notation. Most po-editors will help you
|
||||
with that.
|
||||
|
||||
~~~~~~~~~~~
|
||||
|
||||
Update your po files by new pot files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If a document is updated, it is necessary to generate updated pot files
|
||||
and to apply differences to translated po files.
|
||||
In order to apply the updating difference of a pot file to po file,
|
||||
use the :command:`sphinx-intl update` command.
|
||||
If a document is updated, it is necessary to generate updated pot files and to
|
||||
apply differences to translated po files. In order to apply the updates from a
|
||||
pot file to the po file, use the :command:`sphinx-intl update` command.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -199,7 +206,7 @@ easy to fetch and push translations.
|
||||
.. TODO: why use transifex?
|
||||
|
||||
|
||||
#. Install `transifex-client`_
|
||||
#. Install `transifex-client`_.
|
||||
|
||||
You need :command:`tx` command to upload resources (pot files).
|
||||
|
||||
@@ -209,8 +216,7 @@ easy to fetch and push translations.
|
||||
|
||||
.. seealso:: `Transifex Client documentation`_
|
||||
|
||||
|
||||
#. Create your transifex_ account and create new project for your document
|
||||
#. Create your transifex_ account and create new project for your document.
|
||||
|
||||
Currently, transifex does not allow for a translation project to have more
|
||||
than one version of the document, so you'd better include a version number in
|
||||
@@ -221,8 +227,7 @@ easy to fetch and push translations.
|
||||
:Project ID: ``sphinx-document-test_1_0``
|
||||
:Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/``
|
||||
|
||||
|
||||
#. Create config files for tx command
|
||||
#. Create config files for :command:`tx` command.
|
||||
|
||||
This process will create ``.tx/config`` in the current directory, as well as
|
||||
a ``~/.transifexrc`` file that includes auth information.
|
||||
@@ -238,7 +243,7 @@ easy to fetch and push translations.
|
||||
...
|
||||
Done.
|
||||
|
||||
#. Upload pot files to transifex service
|
||||
#. Upload pot files to transifex service.
|
||||
|
||||
Register pot files to ``.tx/config`` file:
|
||||
|
||||
@@ -259,15 +264,14 @@ easy to fetch and push translations.
|
||||
...
|
||||
Done.
|
||||
|
||||
|
||||
#. Forward the translation on transifex
|
||||
#. Forward the translation on transifex.
|
||||
|
||||
.. TODO: write this section
|
||||
|
||||
#. Pull translated po files and make translated HTML.
|
||||
|
||||
#. Pull translated po files and make translated html
|
||||
|
||||
Get translated catalogs and build mo files (ex. for 'de'):
|
||||
Get translated catalogs and build mo files. For example, to build mo files
|
||||
for German (de):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -278,32 +282,29 @@ easy to fetch and push translations.
|
||||
...
|
||||
Done.
|
||||
|
||||
Invoke make html (for BSD/GNU make):
|
||||
Invoke :command:`make html` (for BSD/GNU make):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make -e SPHINXOPTS="-D language='de'" html
|
||||
|
||||
|
||||
That's all!
|
||||
|
||||
|
||||
.. tip:: Translating locally and on Transifex
|
||||
|
||||
If you want to push all language's po files, you can be done by using
|
||||
:command:`tx push -t` command.
|
||||
Watch out! This operation overwrites translations in transifex.
|
||||
:command:`tx push -t` command. Watch out! This operation overwrites
|
||||
translations in transifex.
|
||||
|
||||
In other words, if you have updated each in the service and local po files,
|
||||
it would take much time and effort to integrate them.
|
||||
|
||||
|
||||
|
||||
Contributing to Sphinx reference translation
|
||||
--------------------------------------------
|
||||
|
||||
The recommended way for new contributors to translate Sphinx reference
|
||||
is to join the translation team on Transifex.
|
||||
The recommended way for new contributors to translate Sphinx reference is to
|
||||
join the translation team on Transifex.
|
||||
|
||||
There is `sphinx translation page`_ for Sphinx (master) documentation.
|
||||
|
||||
@@ -311,8 +312,7 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
|
||||
2. Go to `sphinx translation page`_.
|
||||
3. Click ``Request language`` and fill form.
|
||||
4. Wait acceptance by transifex sphinx translation maintainers.
|
||||
5. (after acceptance) translate on transifex.
|
||||
|
||||
5. (After acceptance) Translate on transifex.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
@@ -321,9 +321,8 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
|
||||
for details on that software suite.
|
||||
.. [2] Because nobody expects the Spanish Inquisition!
|
||||
|
||||
|
||||
.. _`transifex-client`: https://pypi.org/project/transifex-client/
|
||||
.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
|
||||
.. _Transifex: https://www.transifex.com/
|
||||
.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/
|
||||
.. _`Transifex Client documentation`: http://docs.transifex.com/developer/client/
|
||||
.. _`Transifex Client documentation`: https://docs.transifex.com/client/introduction/
|
||||
@@ -65,7 +65,7 @@ The WebSupport Class
|
||||
|
||||
|
||||
Methods
|
||||
~~~~~~~
|
||||
-------
|
||||
|
||||
.. automethod:: sphinxcontrib.websupport.WebSupport.build
|
||||
|
||||
@@ -10,7 +10,7 @@ web application. To learn more read the :ref:`websupportquickstart`.
|
||||
|
||||
.. toctree::
|
||||
|
||||
web/quickstart
|
||||
web/api
|
||||
web/searchadapters
|
||||
web/storagebackends
|
||||
quickstart
|
||||
api
|
||||
searchadapters
|
||||
storagebackends
|
||||
@@ -4,7 +4,7 @@ Web Support Quick Start
|
||||
=======================
|
||||
|
||||
Building Documentation Data
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
----------------------------
|
||||
|
||||
To make use of the web support package in your application you'll need to build
|
||||
the data it uses. This data includes pickle files representing documents,
|
||||
@@ -20,11 +20,11 @@ things are in a document. To do this you will need to create an instance of the
|
||||
|
||||
support.build()
|
||||
|
||||
This will read reStructuredText sources from `srcdir` and place the necessary
|
||||
data in `builddir`. The `builddir` will contain two sub-directories: one named
|
||||
"data" that contains all the data needed to display documents, search through
|
||||
documents, and add comments to documents. The other directory will be called
|
||||
"static" and contains static files that should be served from "/static".
|
||||
This will read reStructuredText sources from ``srcdir`` and place the necessary
|
||||
data in ``builddir``. The ``builddir`` will contain two sub-directories: one
|
||||
named "data" that contains all the data needed to display documents, search
|
||||
through documents, and add comments to documents. The other directory will be
|
||||
called "static" and contains static files that should be served from "/static".
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -34,7 +34,7 @@ documents, and add comments to documents. The other directory will be called
|
||||
|
||||
|
||||
Integrating Sphinx Documents Into Your Webapp
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
----------------------------------------------
|
||||
|
||||
Now that the data is built, it's time to do something useful with it. Start off
|
||||
by creating a :class:`~.WebSupport` object for your application::
|
||||
@@ -96,7 +96,7 @@ integrate with your existing templating system. An example using `Jinja2
|
||||
|
||||
|
||||
Authentication
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
To use certain features such as voting, it must be possible to authenticate
|
||||
users. The details of the authentication are left to your application. Once a
|
||||
@@ -146,13 +146,14 @@ add this data to the ``COMMENT_OPTIONS`` that are used in the template.
|
||||
|
||||
|
||||
Performing Searches
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
-------------------
|
||||
|
||||
To use the search form built-in to the Sphinx sidebar, create a function to
|
||||
handle requests to the url 'search' relative to the documentation root. The
|
||||
handle requests to the URL 'search' relative to the documentation root. The
|
||||
user's search query will be in the GET parameters, with the key `q`. Then use
|
||||
the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to retrieve
|
||||
search results. In `Flask <http://flask.pocoo.org/>`_ that would be like this::
|
||||
the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
|
||||
retrieve search results. In `Flask <http://flask.pocoo.org/>`_ that would be
|
||||
like this::
|
||||
|
||||
@app.route('/search')
|
||||
def search():
|
||||
@@ -167,7 +168,7 @@ does.
|
||||
|
||||
|
||||
Comments & Proposals
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
--------------------
|
||||
|
||||
Now that this is done it's time to define the functions that handle the AJAX
|
||||
calls from the script. You will need three functions. The first function is
|
||||
@@ -186,9 +187,9 @@ used to add a new comment, and will call the web support method
|
||||
username=username, proposal=proposal)
|
||||
return jsonify(comment=comment)
|
||||
|
||||
You'll notice that both a `parent_id` and `node_id` are sent with the
|
||||
request. If the comment is being attached directly to a node, `parent_id`
|
||||
will be empty. If the comment is a child of another comment, then `node_id`
|
||||
You'll notice that both a ``parent_id`` and ``node_id`` are sent with the
|
||||
request. If the comment is being attached directly to a node, ``parent_id``
|
||||
will be empty. If the comment is a child of another comment, then ``node_id``
|
||||
will be empty. Then next function handles the retrieval of comments for a
|
||||
specific node, and is aptly named
|
||||
:meth:`~sphinxcontrib.websupport.WebSupport.get_data`::
|
||||
@@ -217,11 +218,11 @@ and will handle user votes on comments::
|
||||
|
||||
|
||||
Comment Moderation
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
------------------
|
||||
|
||||
By default, all comments added through :meth:`~.WebSupport.add_comment` are
|
||||
automatically displayed. If you wish to have some form of moderation, you can
|
||||
pass the `displayed` keyword argument::
|
||||
pass the ``displayed`` keyword argument::
|
||||
|
||||
comment = support.add_comment(text, node_id='node_id',
|
||||
parent_id='parent_id',
|
||||
@@ -26,13 +26,13 @@ documentation of the :class:`BaseSearch` class below.
|
||||
BaseSearch class is moved to sphinxcontrib.websupport.search from
|
||||
sphinx.websupport.search.
|
||||
|
||||
BaseSearch Methods
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
Methods
|
||||
-------
|
||||
|
||||
The following methods are defined in the BaseSearch class. Some methods do
|
||||
not need to be overridden, but some (:meth:`~BaseSearch.add_document` and
|
||||
:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
|
||||
working example, look at the built-in adapter for whoosh.
|
||||
The following methods are defined in the BaseSearch class. Some methods do not
|
||||
need to be overridden, but some (:meth:`~BaseSearch.add_document` and
|
||||
:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
|
||||
working example, look at the built-in adapter for whoosh.
|
||||
|
||||
.. automethod:: BaseSearch.init_indexing
|
||||
|
||||
@@ -27,8 +27,8 @@ documentation of the :class:`StorageBackend` class below.
|
||||
sphinx.websupport.storage.
|
||||
|
||||
|
||||
StorageBackend Methods
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
Methods
|
||||
-------
|
||||
|
||||
.. automethod:: StorageBackend.pre_build
|
||||
|
||||
@@ -158,23 +158,41 @@ The builder's "name" must be given to the **-b** command-line option of
|
||||
chapter :ref:`latex-options` for details.
|
||||
|
||||
The produced LaTeX file uses several LaTeX packages that may not be present
|
||||
in a "minimal" TeX distribution installation. For example, on Ubuntu, the
|
||||
following packages need to be installed for successful PDF builds:
|
||||
in a "minimal" TeX distribution installation.
|
||||
|
||||
On Ubuntu xenial, the following packages need to be installed for
|
||||
successful PDF builds:
|
||||
|
||||
* ``texlive-latex-recommended``
|
||||
* ``texlive-fonts-recommended``
|
||||
* ``texlive-latex-extra``
|
||||
* ``latexmk`` (for ``make latexpdf`` on GNU/Linux and MacOS X)
|
||||
* ``latex-xcolor`` (old Ubuntu)
|
||||
* ``texlive-luatex``, ``texlive-xetex`` (see :confval:`latex_engine`)
|
||||
* ``latexmk`` (this is a Sphinx requirement on GNU/Linux and MacOS X
|
||||
for functioning of ``make latexpdf``)
|
||||
|
||||
The testing of Sphinx LaTeX is done on Ubuntu trusty with the above
|
||||
mentioned packages, which are from a TeXLive 2013 snapshot dated
|
||||
February 2014.
|
||||
Additional packages are needed in some circumstances (see the discussion of
|
||||
the ``'fontpkg'`` key of :confval:`latex_elements` for more information):
|
||||
|
||||
* to support occasional Cyrillic letters or words, and a fortiori if
|
||||
:confval:`language` is set to a Cyrillic language, the package
|
||||
``texlive-lang-cyrillic`` is required, and, with unmodified ``'fontpkg'``,
|
||||
also ``cm-super`` or ``cm-super-minimal``,
|
||||
* to support occasional Greek letters or words (in text, not in
|
||||
:rst:dir:`math` directive contents), ``texlive-lang-greek`` is required,
|
||||
and, with unmodified ``'fontpkg'``, also ``cm-super`` or
|
||||
``cm-super-minimal``,
|
||||
* for ``'xelatex'`` or ``'lualatex'`` (see :confval:`latex_engine`),
|
||||
``texlive-xetex`` resp. ``texlive-luatex``, and, if leaving unchanged
|
||||
``'fontpkg'``, ``fonts-freefont-otf``.
|
||||
|
||||
The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution
|
||||
is based on a TeXLive 2015 snapshot dated March 2016.
|
||||
|
||||
.. versionchanged:: 1.6
|
||||
Formerly, testing had been done on Ubuntu precise (TeXLive 2009).
|
||||
|
||||
.. versionchanged:: 2.0
|
||||
Formerly, testing had been done on Ubuntu trusty (TeXLive 2013).
|
||||
|
||||
.. note::
|
||||
|
||||
Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows). This
|
||||
@@ -190,20 +208,16 @@ The builder's "name" must be given to the **-b** command-line option of
|
||||
|
||||
reduces console output to a minimum.
|
||||
|
||||
Also, if ``latexmk`` version is 4.52b or higher (Jan 17)
|
||||
``LATEXMKOPTS="-xelatex"`` will speed up PDF builds via XeLateX in case
|
||||
Also, if ``latexmk`` is at version 4.52b or higher (January 2017)
|
||||
``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case
|
||||
of numerous graphics inclusions.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
make latexpdf LATEXMKOPTS="-xelatex"
|
||||
|
||||
To pass options directly to the ``(pdf|xe|lua)latex`` executable, use
|
||||
variable ``LATEXOPTS``.
|
||||
To pass options directly to the ``(pdf|xe|lua)latex`` binary, use
|
||||
variable ``LATEXOPTS``, for example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
make latexpdf LATEXOPTS="--interaction=nonstopmode"
|
||||
make latexpdf LATEXOPTS="--halt-on-error"
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
@@ -215,7 +229,7 @@ Note that a direct PDF builder is being provided by `rinohtype`_. The builder's
|
||||
name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
|
||||
|
||||
.. _rinohtype: https://github.com/brechtm/rinohtype
|
||||
.. _rinohtype manual: http://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
|
||||
.. _rinohtype manual: https://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
|
||||
|
||||
.. module:: sphinx.builders.text
|
||||
.. class:: TextBuilder
|
||||
|
||||
@@ -40,9 +40,7 @@ Important points to note:
|
||||
contain the file name extension.
|
||||
|
||||
* Since :file:`conf.py` is read as a Python file, the usual rules apply for
|
||||
encodings and Unicode support: declare the encoding using an encoding cookie
|
||||
(a comment like ``# -*- coding: utf-8 -*-``) and use Unicode string literals
|
||||
when you include non-ASCII characters in configuration values.
|
||||
encodings and Unicode support.
|
||||
|
||||
* The contents of the config namespace are pickled (so that Sphinx can find out
|
||||
when configuration changes), so it may not contain unpickleable values --
|
||||
@@ -60,6 +58,36 @@ Important points to note:
|
||||
created *after* the builder is initialized.
|
||||
|
||||
|
||||
Project information
|
||||
-------------------
|
||||
|
||||
.. confval:: project
|
||||
|
||||
The documented project's name.
|
||||
|
||||
.. confval:: author
|
||||
|
||||
The author name(s) of the document. The default value is ``'unknown'``.
|
||||
|
||||
.. confval:: copyright
|
||||
|
||||
A copyright statement in the style ``'2008, Author Name'``.
|
||||
|
||||
.. confval:: version
|
||||
|
||||
The major project version, used as the replacement for ``|version|``. For
|
||||
example, for the Python documentation, this may be something like ``2.6``.
|
||||
|
||||
.. confval:: release
|
||||
|
||||
The full project version, used as the replacement for ``|release|`` and
|
||||
e.g. in the HTML templates. For example, for the Python documentation, this
|
||||
may be something like ``2.6.0rc1``.
|
||||
|
||||
If you don't need the separation provided between :confval:`version` and
|
||||
:confval:`release`, just set them both to the same value.
|
||||
|
||||
|
||||
General configuration
|
||||
---------------------
|
||||
|
||||
@@ -98,7 +126,7 @@ General configuration
|
||||
'.md': 'markdown',
|
||||
}
|
||||
|
||||
By default, Sphinx only supports ``'restrcturedtext'`` file type. You can
|
||||
By default, Sphinx only supports ``'restructuredtext'`` file type. You can
|
||||
add a new file type using source parser extensions. Please read a document
|
||||
of the extension to know what file type the extension supports.
|
||||
|
||||
@@ -149,7 +177,10 @@ General configuration
|
||||
.. confval:: master_doc
|
||||
|
||||
The document name of the "master" document, that is, the document that
|
||||
contains the root :rst:dir:`toctree` directive. Default is ``'contents'``.
|
||||
contains the root :rst:dir:`toctree` directive. Default is ``'index'``.
|
||||
|
||||
.. versionchanged:: 2.0
|
||||
The default is changed to ``'index'`` from ``'contents'``.
|
||||
|
||||
.. confval:: exclude_patterns
|
||||
|
||||
@@ -477,36 +508,6 @@ General configuration
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
|
||||
Project information
|
||||
-------------------
|
||||
|
||||
.. confval:: project
|
||||
|
||||
The documented project's name.
|
||||
|
||||
.. confval:: author
|
||||
|
||||
The author name(s) of the document. The default value is ``'unknown'``.
|
||||
|
||||
.. confval:: copyright
|
||||
|
||||
A copyright statement in the style ``'2008, Author Name'``.
|
||||
|
||||
.. confval:: version
|
||||
|
||||
The major project version, used as the replacement for ``|version|``. For
|
||||
example, for the Python documentation, this may be something like ``2.6``.
|
||||
|
||||
.. confval:: release
|
||||
|
||||
The full project version, used as the replacement for ``|release|`` and
|
||||
e.g. in the HTML templates. For example, for the Python documentation, this
|
||||
may be something like ``2.6.0rc1``.
|
||||
|
||||
If you don't need the separation provided between :confval:`version` and
|
||||
:confval:`release`, just set them both to the same value.
|
||||
|
||||
.. confval:: today
|
||||
today_fmt
|
||||
|
||||
@@ -813,7 +814,7 @@ that use Sphinx's HTMLWriter class.
|
||||
.. confval:: html_theme
|
||||
|
||||
The "theme" that the HTML output should use. See the :doc:`section about
|
||||
theming </theming>`. The default is ``'alabaster'``.
|
||||
theming </usage/theming>`. The default is ``'alabaster'``.
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
@@ -1108,12 +1109,6 @@ that use Sphinx's HTMLWriter class.
|
||||
If true, the reST sources are included in the HTML build as
|
||||
:file:`_sources/{name}`. The default is ``True``.
|
||||
|
||||
.. warning::
|
||||
|
||||
If this config value is set to ``False``, the JavaScript search function
|
||||
will only display the titles of matching documents, and no excerpt from
|
||||
the matching contents.
|
||||
|
||||
.. confval:: html_show_sourcelink
|
||||
|
||||
If true (and :confval:`html_copy_source` is true as well), links to the
|
||||
@@ -1251,7 +1246,7 @@ that use Sphinx's HTMLWriter class.
|
||||
|
||||
:'sphinx.search.ja.DefaultSplitter':
|
||||
TinySegmenter algorithm. This is default splitter.
|
||||
:'sphinx.search.ja.MeCabSplitter':
|
||||
:'sphinx.search.ja.MecabSplitter':
|
||||
MeCab binding. To use this splitter, 'mecab' python binding or dynamic
|
||||
link library ('libmecab.so' for linux, 'libmecab.dll' for windows) is
|
||||
required.
|
||||
@@ -1333,6 +1328,16 @@ that use Sphinx's HTMLWriter class.
|
||||
|
||||
.. versionadded:: 1.6
|
||||
|
||||
Options for Single HTML output
|
||||
-------------------------------
|
||||
|
||||
.. confval:: singlehtml_sidebars
|
||||
|
||||
Custom sidebar templates, must be a dictionary that maps document names to
|
||||
template names. And it only allows a key named `'index'`. All other keys
|
||||
are ignored. For more information, refer to :confval:`html_sidebars`. By
|
||||
default, it is same as :confval:`html_sidebars`.
|
||||
|
||||
|
||||
.. _htmlhelp-options:
|
||||
|
||||
@@ -1343,6 +1348,19 @@ Options for HTML help output
|
||||
|
||||
Output file base name for HTML help builder. Default is ``'pydoc'``.
|
||||
|
||||
.. confval:: htmlhelp_file_suffix
|
||||
|
||||
This is the file name suffix for generated HTML help files. The
|
||||
default is ``".html"``.
|
||||
|
||||
.. versionadded:: 2.0
|
||||
|
||||
.. confval:: htmlhelp_link_suffix
|
||||
|
||||
Suffix for generated links to HTML files. The default is ``".html"``.
|
||||
|
||||
.. versionadded:: 2.0
|
||||
|
||||
|
||||
.. _applehelp-options:
|
||||
|
||||
@@ -1763,8 +1781,8 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
|
||||
Options for LaTeX output
|
||||
------------------------
|
||||
|
||||
These options influence LaTeX output. For customization of LaTeX
|
||||
macros and environments, see also :doc:`/latex`.
|
||||
These options influence LaTeX output. Refer to :doc:`/latex` for more
|
||||
information.
|
||||
|
||||
.. confval:: latex_engine
|
||||
|
||||
@@ -1776,24 +1794,29 @@ macros and environments, see also :doc:`/latex`.
|
||||
* ``'lualatex'`` -- LuaLaTeX
|
||||
* ``'platex'`` -- pLaTeX (default if :confval:`language` is ``'ja'``)
|
||||
|
||||
PDFLaTeX's support for Unicode characters covers those from the document
|
||||
language (the LaTeX ``babel`` and ``inputenc`` packages map them to glyph
|
||||
slots in the document font, at various encodings allowing each only 256
|
||||
characters; Sphinx uses by default (except for Cyrillic languages) the
|
||||
``times`` package), but stray characters from other scripts or special
|
||||
symbols may require adding extra LaTeX packages or macros to the LaTeX
|
||||
preamble.
|
||||
``'pdflatex'``\ 's support for Unicode characters is limited.
|
||||
|
||||
If your project uses such extra Unicode characters, switching the engine to
|
||||
XeLaTeX or LuaLaTeX often provides a quick fix. They only work with UTF-8
|
||||
encoded sources and can (in fact, should) use OpenType fonts, either from
|
||||
the system or the TeX install tree. Recent LaTeX releases will default with
|
||||
these engines to the Latin Modern OpenType font, which has good coverage of
|
||||
Latin and Cyrillic scripts (it is provided by standard LaTeX installation),
|
||||
and Sphinx does not modify this default. Refer to the documentation of the
|
||||
LaTeX ``polyglossia`` package to see how to instruct LaTeX to use some
|
||||
other OpenType font if Unicode coverage proves insufficient (or use
|
||||
directly ``\setmainfont`` et. al. as in :ref:`this example <latex-basic>`.)
|
||||
.. note::
|
||||
|
||||
2.0 adds to ``'pdflatex'`` support in Latin language document of
|
||||
occasional Cyrillic or Greek letters or words. This is not automatic,
|
||||
see the discussion of the :confval:`latex_elements` ``'fontenc'`` key.
|
||||
|
||||
If your project uses Unicode characters, setting the engine to
|
||||
``'xelatex'`` or ``'lualatex'`` and making sure to use an OpenType font
|
||||
with wide-enough glyph coverage is often easier than trying to make
|
||||
``'pdflatex'`` work with the extra Unicode characters. Since Sphinx 2.0
|
||||
the default is the GNU FreeFont which covers well Latin, Cyrillic and Greek.
|
||||
|
||||
Contrarily to :ref:`MathJaX math rendering in HTML output <math-support>`,
|
||||
LaTeX requires some extra configuration to support Unicode literals in
|
||||
:rst:dir:`math`: the only comprehensive solution (as far as we know) is to
|
||||
use ``'xelatex'`` or ``'lualatex'`` *and* to add
|
||||
``r'\usepackage{unicode-math}'`` (e.g. via the :confval:`latex_elements`
|
||||
``'preamble'`` key). You may prefer
|
||||
``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode
|
||||
literal such as ``α`` (U+03B1) for example as is in output, rather than
|
||||
being rendered as :math:`\alpha`.
|
||||
|
||||
.. confval:: latex_documents
|
||||
|
||||
@@ -1926,26 +1949,23 @@ macros and environments, see also :doc:`/latex`.
|
||||
__ http://xindy.sourceforge.net/
|
||||
|
||||
- This option is ignored if :confval:`latex_engine` is ``'platex'``
|
||||
(Japanese documents) as :program:`mendex` is used in that case.
|
||||
(Japanese documents; :program:`mendex` replaces :program:`makeindex`
|
||||
then).
|
||||
|
||||
- The default is ``True`` for ``'xelatex'`` or ``'lualatex'`` as
|
||||
:program:`makeindex`, if any indexed term starts with a non-ascii
|
||||
character, creates ``.ind`` file containing invalid bytes for
|
||||
character, creates ``.ind`` files containing invalid bytes for
|
||||
UTF-8 encoding. With ``'lualatex'`` this then breaks the PDF
|
||||
build. Notice that :program:`xindy` supports most but not
|
||||
all European languages.
|
||||
build.
|
||||
|
||||
- The default is ``False`` for ``'pdflatex'`` but ``True`` is
|
||||
recommended for non-English documents as soon as some indexed
|
||||
terms use non-ascii characters from the language script.
|
||||
Cyrillic scripts are (transparently) supported with
|
||||
``'pdflatex'`` thanks to a specific Sphinx-contributed ``xindy``
|
||||
style file :file:`cyrLICRutf8.xdy`.
|
||||
|
||||
As :program:`xindy` does not support the same range of languages
|
||||
as ``LaTeX/babel`` does, the default :program:`makeindex` for
|
||||
``'pdflatex'`` may be preferred in some circumstances, although
|
||||
the index will be ill-formed probably.
|
||||
Sphinx adds to :program:`xindy` base distribution some dedicated support
|
||||
for using ``'pdflatex'`` engine with Cyrillic scripts. And whether with
|
||||
``'pdflatex'`` or Unicode engines, Cyrillic documents handle correctly the
|
||||
indexing of Latin names, even with diacritics.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
@@ -1998,33 +2018,82 @@ macros and environments, see also :doc:`/latex`.
|
||||
``english`` is used if no language.) For Japanese documents, the
|
||||
default is the empty string.
|
||||
|
||||
With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use
|
||||
`polyglossia`_, but one should be aware that current `babel`_ has
|
||||
improved its support for Unicode engines in recent years and for some
|
||||
languages it may make sense to prefer ``babel`` over ``polyglossia``.
|
||||
|
||||
.. hint::
|
||||
|
||||
After modifiying a core LaTeX key like this one, clean up the LaTeX
|
||||
build repertory before next PDF build, else left-over auxiliary
|
||||
files are likely to break the build.
|
||||
|
||||
.. _`polyglossia`: https://ctan.org/pkg/polyglossia
|
||||
.. _`babel`: https://ctan.org/pkg/babel
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
For :confval:`latex_engine` set to ``'xelatex'``, the default
|
||||
is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
|
||||
.. versionchanged:: 1.6
|
||||
``'lualatex'`` uses same default setting as ``'xelatex'``
|
||||
.. versionchanged:: 1.7.6
|
||||
For French, ``xelatex`` and ``lualatex`` default to using
|
||||
``babel``, not ``polyglossia``.
|
||||
|
||||
``'fontpkg'``
|
||||
Font package inclusion, default ``'\\usepackage{times}'`` (which uses
|
||||
Times for text, Helvetica for sans serif and Courier for code-blocks).
|
||||
|
||||
.. hint::
|
||||
|
||||
Courier is much wider than Times, and Sphinx emits LaTeX command
|
||||
``\small`` in code-blocks to compensate. Since ``1.5`` this is not
|
||||
hard-coded anymore: ``\fvset{fontsize=auto}`` can be added to
|
||||
preamble to not change font size in code-blocks. Since ``1.8`` a
|
||||
separate ``'fvset'`` key is provided for this.
|
||||
Font package inclusion, the default is ``'\\usepackage{times}'`` which
|
||||
uses Times for text, Helvetica for sans serif and Courier for monospace.
|
||||
|
||||
.. versionchanged:: 1.2
|
||||
Defaults to ``''`` when the :confval:`language` uses the Cyrillic
|
||||
script.
|
||||
.. versionchanged:: 1.5
|
||||
Defaults to ``''`` when :confval:`latex_engine` is ``'xelatex'``.
|
||||
.. versionchanged:: 1.6
|
||||
Defaults to ``''`` also with ``'lualatex'``.
|
||||
.. versionchanged:: 1.8
|
||||
``'xelatex'`` and ``'lualatex'`` do ``\fvset{fontsize=auto}``.
|
||||
.. versionchanged:: 2.0
|
||||
Support for individual Greek and Cyrillic letters:
|
||||
|
||||
- In order to support occasional Cyrillic (физика частиц)
|
||||
or Greek letters (Σωματιδιακή φυσική) in
|
||||
a document whose language is English or a Latin European
|
||||
one, the default set-up is enhanced (only for ``'pdflatex'``
|
||||
engine) to do:
|
||||
|
||||
.. code-block:: latex
|
||||
|
||||
\substitutefont{LGR}{\rmdefault}{cmr}
|
||||
\substitutefont{LGR}{\sfdefault}{cmss}
|
||||
\substitutefont{LGR}{\ttdefault}{cmtt}
|
||||
\substitutefont{X2}{\rmdefault}{cmr}
|
||||
\substitutefont{X2}{\sfdefault}{cmss}
|
||||
\substitutefont{X2}{\ttdefault}{cmtt}
|
||||
|
||||
but this is activated only under the condition that the
|
||||
``'fontenc'`` key is configured to load the ``LGR`` (Greek)
|
||||
and/or ``X2`` (Cyrillic) pdflatex-font encodings (if the
|
||||
:confval:`language` is set to a Cyrillic language, this
|
||||
``'fontpkg'`` key must be used as "times" package has no direct
|
||||
support for it; then keep only ``LGR`` lines from the above,
|
||||
if support is needed for Greek in the text).
|
||||
|
||||
The ``\substitutefont`` command is from the eponymous LaTeX
|
||||
package, which is loaded by Sphinx if needed (on Ubuntu xenial it
|
||||
is part of ``texlive-latex-extra`` which is a Sphinx
|
||||
requirement).
|
||||
|
||||
Only if the document actually does contain Unicode Greek letters
|
||||
(in text) or Cyrillic letters, will the above default set-up
|
||||
cause additional requirements for the PDF build. On Ubuntu
|
||||
xenial, ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and
|
||||
(with the above choice of fonts) the ``cm-super`` (or
|
||||
``cm-super-minimal``) package.
|
||||
|
||||
- For ``'xelatex'`` and ``'lualatex'``, the default is to
|
||||
use the FreeFont family: this OpenType font family
|
||||
supports both Cyrillic and Greek scripts and is available as
|
||||
separate Ubuntu xenial package ``fonts-freefont-otf``, it is not
|
||||
needed to install the big package ``texlive-fonts-extra``.
|
||||
|
||||
- ``'platex'`` (Japanese documents) engine supports individual
|
||||
Cyrillic and Greek letters with no need of extra user set-up.
|
||||
``'fncychap'``
|
||||
Inclusion of the "fncychap" package (which makes fancy chapter titles),
|
||||
default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation
|
||||
@@ -2034,6 +2103,8 @@ macros and environments, see also :doc:`/latex`.
|
||||
"fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and
|
||||
"Bjornstrup". You can also set this to ``''`` to disable fncychap.
|
||||
|
||||
The default is ``''`` for Japanese documents.
|
||||
|
||||
``'preamble'``
|
||||
Additional preamble content, default empty. See :doc:`/latex`.
|
||||
|
||||
@@ -2101,14 +2172,69 @@ macros and environments, see also :doc:`/latex`.
|
||||
.. versionadded:: 1.2
|
||||
|
||||
``'fontenc'``
|
||||
"fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``.
|
||||
"fontenc" package inclusion, defaults to
|
||||
``'\\usepackage[T1]{fontenc}'``.
|
||||
|
||||
If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR``
|
||||
for support of Greek letters in the document, and also ``X2`` (or
|
||||
``T2A``) for Cyrillic letters, like this:
|
||||
|
||||
.. code-block:: latex
|
||||
|
||||
r'\usepackage[LGR,X2,T1]{fontenc}'
|
||||
|
||||
.. attention::
|
||||
|
||||
Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math
|
||||
mark-up. This is not the case anymore, and the above must be used
|
||||
(only in case of ``'pdflatex'`` engine) if the source contains such
|
||||
Unicode Greek.
|
||||
|
||||
On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
|
||||
(for the latter, only if the ``'fontpkg'`` setting is left to its
|
||||
default) are needed for ``LGR`` to work. In place of ``cm-super``
|
||||
one can install smaller ``cm-super-minimal``, but it requires the
|
||||
LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before
|
||||
loading ``fontenc``. Thus, use this key with this extra at its
|
||||
start if needed.
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
Defaults to ``'\\usepackage{fontspec}'`` when
|
||||
:confval:`latex_engine` is ``'xelatex'``.
|
||||
.. versionchanged:: 1.6
|
||||
``'lualatex'`` also uses ``fontspec`` per default.
|
||||
``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``.
|
||||
.. versionchanged:: 2.0
|
||||
``'lualatex'`` executes
|
||||
``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX
|
||||
ligatures.
|
||||
.. versionchanged:: 2.0
|
||||
Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of
|
||||
occasional Greek or Cyrillic (``'pdflatex'`` only, as this support
|
||||
is provided natively by ``'platex'`` and only requires suitable
|
||||
font with ``'xelatex'/'lualatex'``).
|
||||
|
||||
``'textgreek'``
|
||||
The default (``'pdflatex'`` only) is
|
||||
``'\\usepackage{textalpha}'``, but only if ``'fontenc'`` was
|
||||
modified by user to include ``LGR`` option. If not, the key
|
||||
value will be forced to be the empty string.
|
||||
|
||||
This is needed for ``pdfLaTeX`` to support Unicode input of Greek
|
||||
letters such as φύσις. Expert users may want to load the ``textalpha``
|
||||
package with its option ``normalize-symbols``.
|
||||
|
||||
.. hint::
|
||||
|
||||
Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
|
||||
can be supported by ``'pdflatex'`` from setting this key to
|
||||
``r'\usepackage{textalpha,alphabeta}'``. Then ``:math:`α``` (U+03B1)
|
||||
will render as :math:`\alpha`. For wider Unicode support in math
|
||||
input, see the discussion of :confval:`latex_engine`.
|
||||
|
||||
With ``'platex'`` (Japanese), ``'xelatex'`` or ``'lualatex'``, this
|
||||
key is ignored.
|
||||
|
||||
.. versionadded:: 2.0
|
||||
``'geometry'``
|
||||
"geometry" package inclusion, the default definition is:
|
||||
|
||||
@@ -2153,10 +2279,22 @@ macros and environments, see also :doc:`/latex`.
|
||||
Previously this was done from inside :file:`sphinx.sty`.
|
||||
|
||||
``'maketitle'``
|
||||
"maketitle" call, default ``'\\maketitle'`` (but it has been
|
||||
redefined by the Sphinx ``manual`` and ``howto`` classes.) Override
|
||||
if you want to generate a differently-styled title page.
|
||||
"maketitle" call, default ``'\\sphinxmaketitle'``. Override
|
||||
if you want to generate a differently styled title page.
|
||||
|
||||
.. hint::
|
||||
|
||||
If the key value is set to
|
||||
``r'\newcommand\sphinxbackoftitlepage{<Extra
|
||||
material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
|
||||
typeset on back of title page (``'manual'`` docclass only).
|
||||
|
||||
.. versionchanged:: 1.8.3
|
||||
Original ``\maketitle`` from document class is not overwritten,
|
||||
hence is re-usable as part of some custom setting for this key.
|
||||
.. versionadded:: 1.8.3
|
||||
``\sphinxbackoftitlepage`` optional macro. It can also be defined
|
||||
inside ``'preamble'`` key rather than this one.
|
||||
``'releasename'``
|
||||
value that prefixes ``'release'`` element on title page, default
|
||||
``'Release'``. As for *title* and *author* used in the tuples of
|
||||
@@ -2185,25 +2323,23 @@ macros and environments, see also :doc:`/latex`.
|
||||
Remove unneeded ``{}`` after ``\\hrule``.
|
||||
|
||||
``'printindex'``
|
||||
"printindex" call, the last thing in the file.
|
||||
|
||||
.. versionchanged:: 1.8
|
||||
Former default ``'\\printindex'`` now ``'\\sphinxprintindex'``.
|
||||
This macro works around an issue__ with PDF builds at RTD doing too
|
||||
few ``pdflatex`` runs.
|
||||
|
||||
__ https://github.com/rtfd/readthedocs.org/issues/2857
|
||||
"printindex" call, the last thing in the file, default
|
||||
``'\\printindex'``. Override if you want to generate the index
|
||||
differently or append some content after the index. For example
|
||||
``'\\footnotesize\\raggedright\\printindex'`` is advisable when the
|
||||
index is full of long entries.
|
||||
|
||||
``'fvset'``
|
||||
Customization of ``fancyvrb`` LaTeX package. Defaults to
|
||||
``'\\fvset{fontsize=\\small}'``, because default font (Courier) used in
|
||||
code-blocks is wider and taller than default text font (Times).
|
||||
|
||||
For ``'xelatex'`` and ``'lualatex'``, defaults to
|
||||
``'\\fvset{fontsize=auto}'``, because the default fonts are part of
|
||||
one unified typeface family (Latin Modern OpenType).
|
||||
Customization of ``fancyvrb`` LaTeX package. Sphinx does by default
|
||||
``'fvset': '\\fvset{fontsize=\\small}'``, to adjust for the large
|
||||
character width of the monospace font, used in code-blocks.
|
||||
You may need to modify this if you use custom fonts.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
.. versionchanged:: 2.0
|
||||
Due to new default font choice for ``'xelatex'`` and ``'lualatex'``
|
||||
(FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these
|
||||
engines (and not ``\\fvset{fontsize=auto}``).
|
||||
|
||||
* Keys that are set by other options and therefore should not be overridden
|
||||
are:
|
||||
@@ -2211,10 +2347,8 @@ macros and environments, see also :doc:`/latex`.
|
||||
``'docclass'``
|
||||
``'classoptions'``
|
||||
``'title'``
|
||||
``'date'``
|
||||
``'release'``
|
||||
``'author'``
|
||||
``'logo'``
|
||||
``'makeindex'``
|
||||
|
||||
.. confval:: latex_docclass
|
||||
|
||||
@@ -45,6 +45,10 @@ docstrings to correct reStructuredText before :mod:`autodoc` processes them.
|
||||
.. _NumPy:
|
||||
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
|
||||
|
||||
|
||||
Directives
|
||||
----------
|
||||
|
||||
:mod:`autodoc` provides several directives that are versions of the usual
|
||||
:rst:dir:`py:module`, :rst:dir:`py:class` and so forth. On parsing time, they
|
||||
import the corresponding module and extract the docstring of the given objects,
|
||||
@@ -114,8 +118,17 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
|
||||
.. autoclass:: Noodle
|
||||
:members: eat, slurp
|
||||
|
||||
* If you want to make the ``members`` option (or other flag options described
|
||||
below) the default, see :confval:`autodoc_default_flags`.
|
||||
* If you want to make the ``members`` option (or other options described
|
||||
below) the default, see :confval:`autodoc_default_options`.
|
||||
|
||||
.. tip::
|
||||
|
||||
You can use a negated form, :samp:`'no-{flag}'`, as an option of
|
||||
autodoc directive, to disable it temporarily. For example::
|
||||
|
||||
.. automodule:: foo
|
||||
:no-undoc-members:
|
||||
|
||||
|
||||
* Members without docstrings will be left out, unless you give the
|
||||
``undoc-members`` flag option::
|
||||
@@ -297,6 +310,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
|
||||
well-behaved decorating functions.
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
There are also new config values that you can set:
|
||||
|
||||
.. confval:: autoclass_content
|
||||
@@ -341,20 +357,39 @@ There are also new config values that you can set:
|
||||
This value is a list of autodoc directive flags that should be automatically
|
||||
applied to all autodoc directives. The supported flags are ``'members'``,
|
||||
``'undoc-members'``, ``'private-members'``, ``'special-members'``,
|
||||
``'inherited-members'``, ``'show-inheritance'`` and ``'ignore-module-all'``.
|
||||
|
||||
If you set one of these flags in this config value, you can use a negated
|
||||
form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
|
||||
For example, if ``autodoc_default_flags`` is set to ``['members',
|
||||
'undoc-members']``, and you write a directive like this::
|
||||
|
||||
.. automodule:: foo
|
||||
:no-undoc-members:
|
||||
|
||||
the directive will be interpreted as if only ``:members:`` was given.
|
||||
``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``
|
||||
and ``'exclude-members'``.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
.. deprecated:: 1.8
|
||||
|
||||
Integrated into :confval:`autodoc_default_options`.
|
||||
|
||||
.. confval:: autodoc_default_options
|
||||
|
||||
The default options for autodoc directives. They are applied to all autodoc
|
||||
directives automatically. It must be a dictionary which maps option names
|
||||
to the values. For example::
|
||||
|
||||
autodoc_default_options = {
|
||||
'members': 'var1, var2',
|
||||
'member-order': 'bysource',
|
||||
'special-members': '__init__',
|
||||
'undoc-members': None,
|
||||
'exclude-members': '__weakref__'
|
||||
}
|
||||
|
||||
Setting ``None`` is equivalent to giving the option name in the list format
|
||||
(i.e. it means "yes/true/on").
|
||||
|
||||
The supported options are ``'members'``, ``'member-order'``,
|
||||
``'undoc-members'``, ``'private-members'``, ``'special-members'``,
|
||||
``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'`` and
|
||||
``'exclude-members'``.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
.. confval:: autodoc_docstring_signature
|
||||
|
||||
Functions imported from C modules cannot be introspected, and therefore the
|
||||
@@ -405,6 +440,16 @@ There are also new config values that you can set:
|
||||
|
||||
.. versionadded:: 1.7
|
||||
|
||||
.. confval:: suppress_warnings
|
||||
:noindex:
|
||||
|
||||
:mod:`autodoc` supports to suppress warning messages via
|
||||
:confval:`suppress_warnings`. It allows following warnings types in
|
||||
addition:
|
||||
|
||||
* autodoc
|
||||
* autodoc.import_object
|
||||
|
||||
|
||||
Docstring preprocessing
|
||||
-----------------------
|
||||
|
||||
@@ -208,6 +208,8 @@ The following variables available in the templates:
|
||||
List containing names of all inherited members of class. Only available for
|
||||
classes.
|
||||
|
||||
.. versionadded:: 1.8.0
|
||||
|
||||
.. data:: functions
|
||||
|
||||
List containing names of "public" functions in the module. Here, "public"
|
||||
|
||||
@@ -198,6 +198,81 @@ The following is an example for the usage of the directives. The test via
|
||||
This parrot wouldn't voom if you put 3000 volts through it!
|
||||
|
||||
|
||||
Skipping tests conditionally
|
||||
----------------------------
|
||||
|
||||
``skipif``, a string option, can be used to skip directives conditionally. This
|
||||
may be useful e.g. when a different set of tests should be run depending on the
|
||||
environment (hardware, network/VPN, optional dependencies or different versions
|
||||
of dependencies). The ``skipif`` option is supported by all of the doctest
|
||||
directives. Below are typical use cases for ``skipif`` when used for different
|
||||
directives:
|
||||
|
||||
- :rst:dir:`testsetup` and :rst:dir:`testcleanup`
|
||||
|
||||
- conditionally skip test setup and/or cleanup
|
||||
- customize setup/cleanup code per environment
|
||||
|
||||
- :rst:dir:`doctest`
|
||||
|
||||
- conditionally skip both a test and its output verification
|
||||
|
||||
- :rst:dir:`testcode`
|
||||
|
||||
- conditionally skip a test
|
||||
- customize test code per environment
|
||||
|
||||
- :rst:dir:`testoutput`
|
||||
|
||||
- conditionally skip output assertion for a skipped test
|
||||
- expect different output depending on the environment
|
||||
|
||||
The value of the ``skipif`` option is evaluated as a Python expression. If the
|
||||
result is a true value, the directive is omitted from the test run just as if
|
||||
it wasn't present in the file at all.
|
||||
|
||||
Instead of repeating an expression, the :confval:`doctest_global_setup`
|
||||
configuration option can be used to assign it to a variable which can then be
|
||||
used instead.
|
||||
|
||||
Here's an example which skips some tests if Pandas is not installed:
|
||||
|
||||
.. code-block:: py
|
||||
:caption: conf.py
|
||||
|
||||
extensions = ['sphinx.ext.doctest']
|
||||
doctest_global_setup = '''
|
||||
try:
|
||||
import pandas as pd
|
||||
except ImportError:
|
||||
pd = None
|
||||
'''
|
||||
|
||||
.. code-block:: rst
|
||||
:caption: contents.rst
|
||||
|
||||
.. testsetup::
|
||||
:skipif: pd is None
|
||||
|
||||
data = pd.Series([42])
|
||||
|
||||
.. doctest::
|
||||
:skipif: pd is None
|
||||
|
||||
>>> data.iloc[0]
|
||||
42
|
||||
|
||||
.. testcode::
|
||||
:skipif: pd is None
|
||||
|
||||
print(data.iloc[-1])
|
||||
|
||||
.. testoutput::
|
||||
:skipif: pd is None
|
||||
|
||||
42
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Example Google style docstrings.
|
||||
|
||||
This module demonstrates documentation as specified by the `Google Python
|
||||
@@ -178,7 +177,7 @@ class ExampleError(Exception):
|
||||
self.code = code
|
||||
|
||||
|
||||
class ExampleClass(object):
|
||||
class ExampleClass:
|
||||
"""The summary line for a class docstring should fit on one line.
|
||||
|
||||
If the class has public attributes, they may be documented here
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Example NumPy style docstrings.
|
||||
|
||||
This module demonstrates documentation as specified by the `NumPy
|
||||
@@ -223,7 +222,7 @@ class ExampleError(Exception):
|
||||
self.code = code
|
||||
|
||||
|
||||
class ExampleClass(object):
|
||||
class ExampleClass:
|
||||
"""The summary line for a class docstring should fit on one line.
|
||||
|
||||
If the class has public attributes, they may be documented here
|
||||
|
||||
@@ -54,7 +54,7 @@ It adds this directive:
|
||||
E D F
|
||||
"""
|
||||
|
||||
class A(object):
|
||||
class A:
|
||||
pass
|
||||
|
||||
class B(A):
|
||||
|
||||
@@ -168,6 +168,23 @@ Sphinx.
|
||||
|
||||
The default is empty (``{}``).
|
||||
|
||||
.. confval:: mathjax_config
|
||||
|
||||
The inline configuration options for mathjax. The value is used as a
|
||||
parameter of ``MathJax.Hub.Config()``. For more information, please
|
||||
read `Using in-line configuration options`_.
|
||||
|
||||
For example::
|
||||
|
||||
mathjax_config = {
|
||||
'extensions': ['tex2jax.js'],
|
||||
'jax': ['input/TeX', 'output/HTML-CSS'],
|
||||
}
|
||||
|
||||
The default is empty (not configured).
|
||||
|
||||
.. _Using in-line configuration options: https://docs.mathjax.org/en/latest/configuration.html#using-in-line-configuration-options
|
||||
|
||||
:mod:`sphinx.ext.jsmath` -- Render math via JavaScript
|
||||
------------------------------------------------------
|
||||
|
||||
|
||||
@@ -409,10 +409,10 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
|
||||
|
||||
.. attribute:: attr1
|
||||
|
||||
*int*
|
||||
|
||||
Description of `attr1`
|
||||
|
||||
:type: int
|
||||
|
||||
.. confval:: napoleon_use_param
|
||||
|
||||
True to use a ``:param:`` role for each function parameter. False to
|
||||
|
||||
@@ -25,7 +25,11 @@ from the source to the description will also be inserted.
|
||||
|
||||
In addition, if you don't want to import the modules by ``viewcode``,
|
||||
you can tell the location of the location of source code to ``viewcode``
|
||||
using :event:`viewcode-find-source` event.
|
||||
using the :event:`viewcode-find-source` event.
|
||||
|
||||
If :confval:`viewcode_follow_imported_members` is enabled,
|
||||
you will also need to resolve imported attributes
|
||||
using the :event:`viewcode-follow-imported` event.
|
||||
|
||||
This extension works only on HTML related builders like ``html``,
|
||||
``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except
|
||||
@@ -83,3 +87,13 @@ Configuration
|
||||
|
||||
:param app: The Sphinx application object.
|
||||
:param modname: The name of the module to find source code for.
|
||||
|
||||
.. event:: viewcode-follow-imported (app, modname, attribute)
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
Find the name of the original module for an attribute.
|
||||
|
||||
:param app: The Sphinx application object.
|
||||
:param modname: The name of the module that the attribute belongs to.
|
||||
:param attribute: The name of the member to follow.
|
||||
|
||||
@@ -12,10 +12,9 @@ Installing Sphinx
|
||||
Overview
|
||||
--------
|
||||
|
||||
Sphinx is written in `Python`__ and supports both Python 2.7 and Python 3.3+.
|
||||
We recommend the latter.
|
||||
Sphinx is written in `Python`__ and supports Python 3.5+.
|
||||
|
||||
__ http://docs.python-guide.org/en/latest/
|
||||
__ https://docs.python-guide.org/
|
||||
|
||||
|
||||
Linux
|
||||
@@ -73,7 +72,7 @@ Homebrew
|
||||
|
||||
For more information, refer to the `package overview`__.
|
||||
|
||||
__ http://formulae.brew.sh/formula/sphinx-doc
|
||||
__ https://formulae.brew.sh/formula/sphinx-doc
|
||||
|
||||
MacPorts
|
||||
~~~~~~~~
|
||||
@@ -121,9 +120,9 @@ Once Python is installed, you can install Sphinx using :command:`pip`. Refer
|
||||
to the :ref:`pip installation instructions <install-pypi>` below for more
|
||||
information.
|
||||
|
||||
__ http://docs.python-guide.org/en/latest/
|
||||
__ http://docs.python-guide.org/en/latest/starting/install3/win/
|
||||
__ http://docs.python-guide.org/en/latest/starting/install/win/
|
||||
__ https://docs.python-guide.org/
|
||||
__ https://docs.python-guide.org/starting/install3/win/
|
||||
__ https://docs.python-guide.org/starting/install/win/
|
||||
|
||||
|
||||
.. _install-pypi:
|
||||
|
||||
@@ -15,7 +15,7 @@ parsing the `CommonMark`__ Markdown flavor.
|
||||
__ https://daringfireball.net/projects/markdown/
|
||||
__ https://recommonmark.readthedocs.io/en/latest/index.html
|
||||
__ https://github.com/rtfd/CommonMark-py
|
||||
__ http://commonmark.org/
|
||||
__ https://commonmark.org/
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
@@ -320,8 +320,8 @@ More topics to be covered
|
||||
|
||||
- :doc:`Other extensions </usage/extensions/index>`:
|
||||
- Static files
|
||||
- :doc:`Selecting a theme </theming>`
|
||||
- :doc:`/setuptools`
|
||||
- :doc:`Selecting a theme </usage/theming>`
|
||||
- :doc:`/usage/advanced/setuptools`
|
||||
- :ref:`Templating <templating>`
|
||||
- Using extensions
|
||||
- :ref:`Writing extensions <dev-extensions>`
|
||||
|
||||
@@ -1063,6 +1063,15 @@ or use Python raw strings (``r"raw"``).
|
||||
|
||||
.. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`math-support`
|
||||
Rendering options for math with HTML builders.
|
||||
|
||||
:confval:`latex_engine`
|
||||
Explains how to configure LaTeX builder to support Unicode literals in
|
||||
math mark-up.
|
||||
|
||||
|
||||
Grammar production displays
|
||||
---------------------------
|
||||
|
||||
@@ -850,8 +850,8 @@ Note however that no checking is performed with respect to parameter
|
||||
compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction
|
||||
even though it would not be valid C++.
|
||||
|
||||
Inline Expressions and Tpes
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Inline Expressions and Types
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. rst:role:: cpp:expr
|
||||
cpp:texpr
|
||||
@@ -1005,20 +1005,46 @@ These roles link to the given declaration types:
|
||||
When a custom title is not needed it may be useful to use the roles for inline expressions,
|
||||
:rst:role:`cpp:expr` and :rst:role:`cpp:texpr`, where angle brackets do not need escaping.
|
||||
|
||||
.. admonition:: Note on References to Overloaded Functions
|
||||
|
||||
It is currently impossible to link to a specific version of an overloaded
|
||||
function. Currently the C++ domain is the first domain that has basic
|
||||
support for overloaded functions and until there is more data for comparison
|
||||
we don't want to select a bad syntax to reference a specific overload.
|
||||
Currently Sphinx will link to the first overloaded version of the function.
|
||||
|
||||
Declarations without template parameters and template arguments
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For linking to non-templated declarations the name must be a nested name, e.g.,
|
||||
``f`` or ``MyClass::f``.
|
||||
|
||||
|
||||
Overloaded (member) functions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When a (member) function is referenced using just its name, the reference
|
||||
will point to an arbitrary matching overload.
|
||||
The :rst:role:`cpp:any` and :rst:role:`cpp:func` roles will an alternative
|
||||
format, which simply is a complete function declaration.
|
||||
This will resolve to the exact matching overload.
|
||||
As example, consider the following class declaration:
|
||||
|
||||
.. cpp:namespace-push:: overload_example
|
||||
.. cpp:class:: C
|
||||
|
||||
.. cpp:function:: void f(double d) const
|
||||
.. cpp:function:: void f(double d)
|
||||
.. cpp:function:: void f(int i)
|
||||
.. cpp:function:: void f()
|
||||
|
||||
References using the :rst:role:`cpp:func` role:
|
||||
|
||||
- Arbitrary overload: ``C::f``, :cpp:func:`C::f`
|
||||
- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()`
|
||||
- Specific overload: ``void C::f()``, :cpp:func:`void C::f()`
|
||||
- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)`
|
||||
- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)`
|
||||
- Specific overload: ``void C::f(double) const``, :cpp:func:`void C::f(double) const`
|
||||
|
||||
Note that the :confval:`add_function_parentheses` configuration variable
|
||||
does not influence specific overload references.
|
||||
|
||||
.. cpp:namespace-pop::
|
||||
|
||||
|
||||
Templated declarations
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -1033,19 +1059,25 @@ Assume the following declarations.
|
||||
Inner
|
||||
|
||||
In general the reference must include the template parameter declarations,
|
||||
e.g., ``template\<typename TOuter> Wrapper::Outer``
|
||||
(:cpp:class:`template\<typename TOuter> Wrapper::Outer`). Currently the lookup
|
||||
only succeed if the template parameter identifiers are equal strings. That is,
|
||||
``template\<typename UOuter> Wrapper::Outer`` will not work.
|
||||
and template arguments for the prefix of qualified names. For example:
|
||||
|
||||
The inner class template cannot be directly referenced, unless the current
|
||||
namespace is changed or the following shorthand is used. If a template
|
||||
parameter list is omitted, then the lookup will assume either a template or a
|
||||
non-template, but not a partial template specialisation. This means the
|
||||
following references work.
|
||||
- ``template\<typename TOuter> Wrapper::Outer``
|
||||
(:cpp:class:`template\<typename TOuter> Wrapper::Outer`)
|
||||
- ``template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner``
|
||||
(:cpp:class:`template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner`)
|
||||
|
||||
- ``Wrapper::Outer`` (:cpp:class:`Wrapper::Outer`)
|
||||
- ``Wrapper::Outer::Inner`` (:cpp:class:`Wrapper::Outer::Inner`)
|
||||
Currently the lookup only succeed if the template parameter identifiers are equal strings.
|
||||
That is, ``template\<typename UOuter> Wrapper::Outer`` will not work.
|
||||
|
||||
As a shorthand notation, if a template parameter list is omitted,
|
||||
then the lookup will assume either a primary template or a non-template,
|
||||
but not a partial template specialisation.
|
||||
This means the following references work as well:
|
||||
|
||||
- ``Wrapper::Outer``
|
||||
(:cpp:class:`Wrapper::Outer`)
|
||||
- ``Wrapper::Outer::Inner``
|
||||
(:cpp:class:`Wrapper::Outer::Inner`)
|
||||
- ``template\<typename TInner> Wrapper::Outer::Inner``
|
||||
(:cpp:class:`template\<typename TInner> Wrapper::Outer::Inner`)
|
||||
|
||||
@@ -1325,6 +1357,25 @@ These roles are provided to refer to the described objects:
|
||||
.. rst:role:: rst:dir
|
||||
rst:role
|
||||
|
||||
.. _math-domain:
|
||||
|
||||
The Math Domain
|
||||
---------------
|
||||
|
||||
The math domain (name **math**) provides the following roles::
|
||||
|
||||
.. rst:role:: math:numref
|
||||
|
||||
Role for cross-referencing equations defined by :rst:dir:`math` directive
|
||||
via their label. Example::
|
||||
|
||||
.. math:: e^{i\pi} + 1 = 0
|
||||
:label: euler
|
||||
|
||||
Euler's identity, equation :math:numref:`euler`, was elected one of the
|
||||
most beautiful mathematical formulas.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
More domains
|
||||
------------
|
||||
|
||||
@@ -288,13 +288,7 @@ Math
|
||||
|
||||
.. rst:role:: eq
|
||||
|
||||
Role for cross-referencing equations via their label. Example::
|
||||
|
||||
.. math:: e^{i\pi} + 1 = 0
|
||||
:label: euler
|
||||
|
||||
Euler's identity, equation :eq:`euler`, was elected one of the most
|
||||
beautiful mathematical formulas.
|
||||
Same as :rst:role:`math:numref`.
|
||||
|
||||
|
||||
Other semantic markup
|
||||
|
||||
339
doc/usage/theming.rst
Normal file
339
doc/usage/theming.rst
Normal file
@@ -0,0 +1,339 @@
|
||||
.. highlight:: python
|
||||
|
||||
HTML
|
||||
====
|
||||
|
||||
Sphinx provides a number of builders for HTML and HTML-based formats.
|
||||
|
||||
Builders
|
||||
--------
|
||||
|
||||
.. todo:: Populate when the 'builders' document is split up.
|
||||
|
||||
|
||||
Themes
|
||||
------
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
.. note::
|
||||
|
||||
This section provides information about using pre-existing HTML themes. If
|
||||
you wish to create your own theme, refer to :doc:`/theming`.
|
||||
|
||||
Sphinx supports changing the appearance of its HTML output via *themes*. A
|
||||
theme is a collection of HTML templates, stylesheet(s) and other static files.
|
||||
Additionally, it has a configuration file which specifies from which theme to
|
||||
inherit, which highlighting style to use, and what options exist for customizing
|
||||
the theme's look and feel.
|
||||
|
||||
Themes are meant to be project-unaware, so they can be used for different
|
||||
projects without change.
|
||||
|
||||
Using a theme
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Using a :ref:`theme provided with Sphinx <builtin-themes>` is easy. Since these
|
||||
do not need to be installed, you only need to set the :confval:`html_theme`
|
||||
config value. For example, to enable the ``classic`` theme, add the following
|
||||
to :file:`conf.py`::
|
||||
|
||||
html_theme = "classic"
|
||||
|
||||
You can also set theme-specific options using the :confval:`html_theme_options`
|
||||
config value. These options are generally used to change the look and feel of
|
||||
the theme. For example, to place the sidebar on the right side and a black
|
||||
background for the relation bar (the bar with the navigation links at the
|
||||
page's top and bottom), add the following :file:`conf.py`::
|
||||
|
||||
html_theme_options = {
|
||||
"rightsidebar": "true",
|
||||
"relbarbgcolor": "black"
|
||||
}
|
||||
|
||||
If the theme does not come with Sphinx, it can be in two static forms or as a
|
||||
Python package. For the static forms, either a directory (containing
|
||||
:file:`theme.conf` and other needed files), or a zip file with the same
|
||||
contents is supported. The directory or zipfile must be put where Sphinx can
|
||||
find it; for this there is the config value :confval:`html_theme_path`. This
|
||||
can be a list of directories, relative to the directory containing
|
||||
:file:`conf.py`, that can contain theme directories or zip files. For example,
|
||||
if you have a theme in the file :file:`blue.zip`, you can put it right in the
|
||||
directory containing :file:`conf.py` and use this configuration::
|
||||
|
||||
html_theme = "blue"
|
||||
html_theme_path = ["."]
|
||||
|
||||
The third form is a Python package. If a theme you want to use is distributed
|
||||
as a Python package, you can use it after installing
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# installing theme package
|
||||
$ pip install sphinxjp.themes.dotted
|
||||
|
||||
Once installed, this can be used in the same manner as a directory or
|
||||
zipfile-based theme::
|
||||
|
||||
html_theme = "dotted"
|
||||
|
||||
For more information on the design of themes, including information about
|
||||
writing your own themes, refer to :doc:`/theming`.
|
||||
|
||||
.. _builtin-themes:
|
||||
|
||||
Builtin themes
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |alabaster| | |classic| |
|
||||
| | |
|
||||
| *alabaster* | *classic* |
|
||||
+--------------------+--------------------+
|
||||
| |sphinxdoc| | |scrolls| |
|
||||
| | |
|
||||
| *sphinxdoc* | *scrolls* |
|
||||
+--------------------+--------------------+
|
||||
| |agogo| | |traditional| |
|
||||
| | |
|
||||
| *agogo* | *traditional* |
|
||||
+--------------------+--------------------+
|
||||
| |nature| | |haiku| |
|
||||
| | |
|
||||
| *nature* | *haiku* |
|
||||
+--------------------+--------------------+
|
||||
| |pyramid| | |bizstyle| |
|
||||
| | |
|
||||
| *pyramid* | *bizstyle* |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |alabaster| image:: /_static/themes/alabaster.png
|
||||
.. |classic| image:: /_static/themes/classic.png
|
||||
.. |sphinxdoc| image:: /_static/themes/sphinxdoc.png
|
||||
.. |scrolls| image:: /_static/themes/scrolls.png
|
||||
.. |agogo| image:: /_static/themes/agogo.png
|
||||
.. |traditional| image:: /_static/themes/traditional.png
|
||||
.. |nature| image:: /_static/themes/nature.png
|
||||
.. |haiku| image:: /_static/themes/haiku.png
|
||||
.. |pyramid| image:: /_static/themes/pyramid.png
|
||||
.. |bizstyle| image:: /_static/themes/bizstyle.png
|
||||
|
||||
Sphinx comes with a selection of themes to choose from.
|
||||
|
||||
.. cssclass:: clear
|
||||
|
||||
These themes are:
|
||||
|
||||
**basic**
|
||||
This is a basically unstyled layout used as the base for the
|
||||
other themes, and usable as the base for custom themes as well. The HTML
|
||||
contains all important elements like sidebar and relation bar. There are
|
||||
these options (which are inherited by the other themes):
|
||||
|
||||
- **nosidebar** (true or false): Don't include the sidebar. Defaults to
|
||||
``False``.
|
||||
|
||||
- **sidebarwidth** (int or str): Width of the sidebar in pixels.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Defaults to 230 pixels.
|
||||
|
||||
- **body_min_width** (int or str): Minimal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 0 if you don't want
|
||||
a width limit. Defaults may depend on the theme (often 450px).
|
||||
|
||||
- **body_max_width** (int or str): Maximal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 'none' if you don't
|
||||
want a width limit. Defaults may depend on the theme (often 800px).
|
||||
|
||||
**alabaster**
|
||||
`Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
|
||||
(especially as used in his Requests project), which was itself originally
|
||||
based on @mitsuhiko's theme used for Flask & related projects. Refer to its
|
||||
`installation page`_ for information on how to configure
|
||||
:confval:`html_sidebars` for its use.
|
||||
|
||||
.. _Alabaster theme: https://pypi.org/project/alabaster/
|
||||
.. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html
|
||||
|
||||
**classic**
|
||||
This is the classic theme, which looks like `the Python 2
|
||||
documentation <https://docs.python.org/2/>`_. It can be customized via
|
||||
these options:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **stickysidebar** (true or false): Make the sidebar "fixed" so that it
|
||||
doesn't scroll out of view for long body content. This may not work well
|
||||
with all browsers. Defaults to ``False``.
|
||||
|
||||
- **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
|
||||
snippet that makes the sidebar collapsible via a button on its side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **externalrefs** (true or false): Display external links differently from
|
||||
internal links. Defaults to ``False``.
|
||||
|
||||
There are also various color and font options that can change the color scheme
|
||||
without having to write a custom stylesheet:
|
||||
|
||||
- **footerbgcolor** (CSS color): Background color for the footer line.
|
||||
- **footertextcolor** (CSS color): Text color for the footer line.
|
||||
- **sidebarbgcolor** (CSS color): Background color for the sidebar.
|
||||
- **sidebarbtncolor** (CSS color): Background color for the sidebar collapse
|
||||
button (used when *collapsiblesidebar* is ``True``).
|
||||
- **sidebartextcolor** (CSS color): Text color for the sidebar.
|
||||
- **sidebarlinkcolor** (CSS color): Link color for the sidebar.
|
||||
- **relbarbgcolor** (CSS color): Background color for the relation bar.
|
||||
- **relbartextcolor** (CSS color): Text color for the relation bar.
|
||||
- **relbarlinkcolor** (CSS color): Link color for the relation bar.
|
||||
- **bgcolor** (CSS color): Body background color.
|
||||
- **textcolor** (CSS color): Body text color.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **visitedlinkcolor** (CSS color): Body color for visited links.
|
||||
- **headbgcolor** (CSS color): Background color for headings.
|
||||
- **headtextcolor** (CSS color): Text color for headings.
|
||||
- **headlinkcolor** (CSS color): Link color for headings.
|
||||
- **codebgcolor** (CSS color): Background color for code blocks.
|
||||
- **codetextcolor** (CSS color): Default text color for code blocks, if not
|
||||
set differently by the highlighting style.
|
||||
|
||||
- **bodyfont** (CSS font-family): Font for normal text.
|
||||
- **headfont** (CSS font-family): Font for headings.
|
||||
|
||||
**sphinxdoc**
|
||||
The theme originally used by this documentation. It features
|
||||
a sidebar on the right side. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
.. note::
|
||||
|
||||
The Sphinx documentation now uses
|
||||
`an adjusted version of the sphinxdoc theme
|
||||
<https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_.
|
||||
|
||||
**scrolls**
|
||||
A more lightweight theme, based on `the Jinja documentation
|
||||
<http://jinja.pocoo.org/>`_. The following color options are available:
|
||||
|
||||
- **headerbordercolor**
|
||||
- **subheadlinecolor**
|
||||
- **linkcolor**
|
||||
- **visitedlinkcolor**
|
||||
- **admonitioncolor**
|
||||
|
||||
**agogo**
|
||||
A theme created by Andi Albrecht. The following options are supported:
|
||||
|
||||
- **bodyfont** (CSS font family): Font for normal text.
|
||||
- **headerfont** (CSS font family): Font for headings.
|
||||
- **pagewidth** (CSS length): Width of the page content, default 70em.
|
||||
- **documentwidth** (CSS length): Width of the document (without sidebar),
|
||||
default 50em.
|
||||
- **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
|
||||
- **bgcolor** (CSS color): Background color.
|
||||
- **headerbg** (CSS value for "background"): background for the header area,
|
||||
default a grayish gradient.
|
||||
- **footerbg** (CSS value for "background"): background for the footer area,
|
||||
default a light gray gradient.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
|
||||
headings.
|
||||
- **headerlinkcolor** (CSS color): Color for the backreference link in
|
||||
headings.
|
||||
- **textalign** (CSS *text-align* value): Text alignment for the body, default
|
||||
is ``justify``.
|
||||
|
||||
**nature**
|
||||
A greenish theme. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
**pyramid**
|
||||
A theme from the Pyramid web framework project, designed by Blaise Laflamme.
|
||||
There are currently no options beyond *nosidebar* and *sidebarwidth*.
|
||||
|
||||
**haiku**
|
||||
A theme without sidebar inspired by the `Haiku OS user guide
|
||||
<https://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following
|
||||
options are supported:
|
||||
|
||||
- **full_logo** (true or false, default ``False``): If this is true, the
|
||||
header will only show the :confval:`html_logo`. Use this for large logos.
|
||||
If this is false, the logo (if present) will be shown floating right, and
|
||||
the documentation title will be put in the header.
|
||||
|
||||
- **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
|
||||
**hoverlinkcolor** (CSS colors): Colors for various body elements.
|
||||
|
||||
**traditional**
|
||||
A theme resembling the old Python documentation. There are
|
||||
currently no options beyond *nosidebar* and *sidebarwidth*.
|
||||
|
||||
**epub**
|
||||
A theme for the epub builder. This theme tries to save visual
|
||||
space which is a sparse resource on ebook readers. The following options
|
||||
are supported:
|
||||
|
||||
- **relbar1** (true or false, default ``True``): If this is true, the
|
||||
`relbar1` block is inserted in the epub output, otherwise it is omitted.
|
||||
|
||||
- **footer** (true or false, default ``True``): If this is true, the
|
||||
`footer` block is inserted in the epub output, otherwise it is omitted.
|
||||
|
||||
**bizstyle**
|
||||
A simple bluish theme. The following options are supported
|
||||
beyond *nosidebar* and *sidebarwidth*:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
|
||||
|
||||
.. versionchanged:: 1.3
|
||||
The 'default' theme has been renamed to 'classic'. 'default' is still
|
||||
available, however it will emit a notice that it is an alias for the new
|
||||
'alabaster' theme.
|
||||
|
||||
Third Party Themes
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |sphinx_rtd_theme| | |
|
||||
| | |
|
||||
| *sphinx_rtd_theme* | |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |sphinx_rtd_theme| image:: /_static/themes/sphinx_rtd_theme.png
|
||||
|
||||
There are many third-party themes available. Some of these are general use,
|
||||
while others are specific to an individual project. A section of third-party
|
||||
themes is listed below. Many more can be found on PyPI__, GitHub__ and
|
||||
sphinx-themes.org__.
|
||||
|
||||
.. cssclass:: clear
|
||||
|
||||
**sphinx_rtd_theme**
|
||||
`Read the Docs Sphinx Theme`_.
|
||||
This is a mobile-friendly sphinx theme that was made for readthedocs.org.
|
||||
View a working demo over on readthedocs.org. You can get install and options
|
||||
information at `Read the Docs Sphinx Theme`_ page.
|
||||
|
||||
.. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/
|
||||
|
||||
.. versionchanged:: 1.4
|
||||
**sphinx_rtd_theme** has become optional.
|
||||
|
||||
.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
|
||||
.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type=
|
||||
.. __: https://sphinx-themes.org/
|
||||
Reference in New Issue
Block a user