diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 89dc8fde9c..3cdda918c6 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -4,16 +4,12 @@ on: [push, pull_request]
jobs:
ubuntu:
- runs-on: ${{ matrix.os }}
+ runs-on: ubuntu-18.04
strategy:
fail-fast: false
matrix:
- name: [py35, py36, py37, py38, py39]
- os: [ubuntu-16.04]
+ name: [py36, py37, py38, py39, py310-dev]
include:
- - name: py35
- python: 3.5
- docutils: du12
- name: py36
python: 3.6
docutils: du13
@@ -30,7 +26,6 @@ jobs:
- name: py310-dev
python: 3.10-dev
docutils: du16
- os: ubuntu-latest # required
env:
PYTEST_ADDOPTS: ${{ matrix.coverage }}
diff --git a/CHANGES b/CHANGES
index 8fa86a98b2..ad3c20988e 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,113 @@
+Release 4.0.0 (in development)
+==============================
+
+Dependencies
+------------
+
+* Drop python 3.5 support
+* Drop docutils 0.12 and 0.13 support
+* LaTeX: add ``tex-gyre`` font dependency
+
+Incompatible changes
+--------------------
+
+* domain: The ``Index`` class becomes subclasses of ``abc.ABC`` to indicate
+ methods that must be overrided in the concrete classes
+* #4826: py domain: The structure of python objects is changed. A boolean value
+ is added to indicate that the python object is canonical one
+* #7425: MathJax: The MathJax was changed from 2 to 3. Users using a custom
+ MathJax configuration may have to set the old MathJax path or update their
+ configuration for version 3. See :mod:`sphinx.ext.mathjax`.
+* #7784: i18n: The msgid for alt text of image is changed
+* #5560: napoleon: :confval:`napoleon_use_param` also affect "other parameters"
+ section
+* #7996: manpage: Make a section directory on build manpage by default (see
+ :confval:`man_make_section_directory`)
+* #7849: html: Change the default setting of
+ :confval:`html_codeblock_linenos_style` to ``'inline'``
+* #8380: html search: search results are wrapped with ``
`` instead of
+ ``
``
+* html theme: Move a script tag for documentation_options.js in
+ basic/layout.html to ``script_files`` variable
+* html theme: Move CSS tags in basic/layout.html to ``css_files`` variable
+* #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older
+* #8508: LaTeX: uplatex becomes a default setting of latex_engine for Japanese
+ documents
+* #5977: py domain: ``:var:``, ``:cvar:`` and ``:ivar:`` fields do not create
+ cross-references
+* #4550: The ``align`` attribute of ``figure`` and ``table`` nodes becomes
+ ``None`` by default instead of ``'default'``
+* #8769: LaTeX refactoring: split sphinx.sty into multiple files and rename
+ some auxiliary files created in ``latex`` build output repertory
+* #8937: Use explicit title instead of
+* #8487: The :file: option for csv-table directive now recognizes an absolute
+ path as a relative path from source directory
+
+Deprecated
+----------
+
+* :confval:`html_codeblock_linenos_style`
+* ``favicon`` and ``logo`` variable in HTML templates
+* ``sphinx.directives.patches.CSVTable``
+* ``sphinx.directives.patches.ListTable``
+* ``sphinx.directives.patches.RSTTable``
+* ``sphinx.registry.SphinxComponentRegistry.get_source_input()``
+* ``sphinx.registry.SphinxComponentRegistry.source_inputs``
+* ``sphinx.transforms.FigureAligner``
+* ``sphinx.util.pycompat.convert_with_2to3()``
+* ``sphinx.util.pycompat.execfile_()``
+* ``sphinx.util.smartypants``
+
+Features added
+--------------
+
+* #8924: autodoc: Support ``bound`` argument for TypeVar
+* #7549: autosummary: Enable :confval:`autosummary_generate` by default
+* #4826: py domain: Add ``:canonical:`` option to python directives to describe
+ the location where the object is defined
+* #7199: py domain: Add :confval:`python_use_unqualified_type_names` to suppress
+ the module name of the python reference if it can be resolved (experimental)
+* #7784: i18n: The alt text for image is translated by default (without
+ :confval:`gettext_additional_targets` setting)
+* #2018: html: :confval:`html_favicon` and :confval:`html_logo` now accept URL
+ for the image
+* #8070: html search: Support searching for 2characters word
+* #8938: imgconverter: Show the error of the command availability check
+* #7830: Add debug logs for change detection of sources and templates
+* #8201: Emit a warning if toctree contains duplicated entries
+* #8326: ``master_doc`` is now renamed to :confval:`root_doc`
+* #8942: C++, add support for the C++20 spaceship operator, ``<=>``.
+* #7199: A new node, ``sphinx.addnodes.pending_xref_condition`` has been added.
+ It can be used to choose appropriate content of the reference by conditions.
+
+Bugs fixed
+----------
+
+* #8917: autodoc: Raises a warning if function has wrong __globals__ value
+* #8415: autodoc: a TypeVar imported from other module is not resolved (in
+ Python 3.7 or above)
+* #8905: html: html_add_permalinks=None and html_add_permalinks="" are ignored
+* #8380: html search: Paragraphs in search results are not identified as ``
``
+* #8915: html theme: The translation of sphinx_rtd_theme does not work
+* #8342: Emit a warning if a unknown domain is given for directive or role (ex.
+ ``:unknown:doc:``)
+* #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning (and font
+ change) with late TeXLive 2019
+* #8253: LaTeX: Figures with no size defined get overscaled (compared to images
+ with size explicitly set in pixels) (fixed for ``'pdflatex'/'lualatex'`` only)
+* #8925: LaTeX: 3.5.0 ``verbatimmaxunderfull`` setting does not work as
+ expected
+* #8911: C++: remove the longest matching prefix in
+ :confval:`cpp_index_common_prefix` instead of the first that matches.
+* C, properly reject function declarations when a keyword is used
+ as parameter name.
+* #8933: viewcode: Failed to create back-links on parallel build
+* #8960: C and C++, fix rendering of (member) function pointer types in
+ function parameter lists.
+
+Testing
+--------
+
Release 3.5.3 (in development)
==============================
@@ -92,6 +202,9 @@ Features added
* #8775: autodoc: Support type union operator (PEP-604) in Python 3.10 or above
* #8297: autodoc: Allow to extend :confval:`autodoc_default_options` via
directive options
+* #759: autodoc: Add a new configuration :confval:`autodoc_preserve_defaults` as
+ an experimental feature. It preserves the default argument values of
+ functions in source code and keep them not evaluated for readability.
* #8619: html: kbd role generates customizable HTML tags for compound keys
* #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter
for :meth:`Sphinx.add_js_file()` and :meth:`Sphinx.add_css_file()`
diff --git a/EXAMPLES b/EXAMPLES
index 348e76c8ca..040637e964 100644
--- a/EXAMPLES
+++ b/EXAMPLES
@@ -12,19 +12,20 @@ interesting examples.
Documentation using the alabaster theme
---------------------------------------
+* `AIOHTTP `__
* `Alabaster `__
* `Blinker `__
* `Calibre `__
-* `Click `__ (customized)
+* `Click `__ (customized)
* `coala `__ (customized)
* `CodePy `__
* `Eve `__ (Python REST API framework)
* `Fabric `__
* `Fityk `__
-* `Flask `__
+* `Flask `__
* `Flask-OpenID `__
* `Invoke `__
-* `Jinja `__
+* `Jinja `__
* `Lino `__ (customized)
* `marbl `__
* `MDAnalysis `__ (customized)
@@ -41,7 +42,8 @@ Documentation using the alabaster theme
* `Spyder `__ (customized)
* `Tablib `__
* `urllib3 `__ (customized)
-* `Werkzeug `__ (customized)
+* `Werkzeug `__
+* `Write the Docs `__
Documentation using the classic theme
-------------------------------------
@@ -132,7 +134,7 @@ Documentation using the sphinxdoc theme
Documentation using the nature theme
------------------------------------
-* `Alembic `__
+* `Alembic `__
* `Cython `__
* `easybuild `__
* `jsFiddle `__
@@ -141,6 +143,7 @@ Documentation using the nature theme
* `MapServer `__ (customized)
* `Pandas `__
* `pyglet `__ (customized)
+* `PyWavelets `__
* `Setuptools `__
* `Spring Python `__
* `StatsModels `__ (customized)
@@ -156,6 +159,7 @@ Documentation using another builtin theme
* `PyPubSub `__ (bizstyle)
* `Pylons `__ (pyramid)
* `Pyramid web framework `__ (pyramid)
+* `RxDock `__
* `Sphinx `__ (sphinx13) :-)
* `Valence `__ (haiku, customized)
@@ -219,6 +223,7 @@ Documentation using sphinx_rtd_theme
* `Mailman `__
* `MathJax `__
* `MDTraj `__ (customized)
+* `Mesa 3D `__
* `micca - MICrobial Community Analysis `__
* `MicroPython `__
* `Minds `__ (customized)
@@ -227,6 +232,7 @@ Documentation using sphinx_rtd_theme
* `mod_wsgi `__
* `MoinMoin `__
* `Mopidy `__
+* `mpi4py `__
* `MyHDL `__
* `Nextflow `__
* `NICOS `__ (customized)
@@ -247,6 +253,7 @@ Documentation using sphinx_rtd_theme
* `PyVISA `__
* `pyvista `__
* `Read The Docs `__
+* `ROCm Platform `__
* `Free your information from their silos (French) `__ (customized)
* `Releases Sphinx extension `__
* `Qtile `__
@@ -254,7 +261,7 @@ Documentation using sphinx_rtd_theme
* `QuTiP `__
* `Satchmo `__
* `Scapy `__
-* `SimGrid `__
+* `SimGrid `__
* `SimPy `__
* `six `__
* `SlamData `__
@@ -283,7 +290,6 @@ Documentation using sphinx_rtd_theme
* `Web Application Attack and Audit Framework (w3af) `__
* `Weblate `__
* `x265 `__
-* `ZeroNet `__
* `Zulip `__
Documentation using sphinx_bootstrap_theme
@@ -319,6 +325,7 @@ Documentation using a custom theme or integrated in a website
* `Doctrine `__
* `Enterprise Toolkit for Acrobat products `__
* `FreeFEM `__
+* `fmt `__
* `Gameduino `__
* `gensim `__
* `GeoServer `__
@@ -328,6 +335,7 @@ Documentation using a custom theme or integrated in a website
* `H2O.ai `__
* `Heka `__
* `Istihza (Turkish Python documentation project) `__
+* `JupyterHub `__
* `Kombu `__
* `Lasso `__
* `Mako `__
diff --git a/MANIFEST.in b/MANIFEST.in
index 1114ca19f8..7c2f852a81 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -15,6 +15,7 @@ include sphinx-quickstart.py
include sphinx-apidoc.py
include tox.ini
include sphinx/locale/.tx/config
+include sphinx/py.typed
recursive-include sphinx/templates *
recursive-include sphinx/texinputs *
diff --git a/bindep.txt b/bindep.txt
index dfee52c281..0c599b9f2b 100644
--- a/bindep.txt
+++ b/bindep.txt
@@ -12,10 +12,12 @@ texlive-luatex85 [platform:rpm]
texlive-anyfontsize [platform:rpm]
texlive-ctablestack [platform:rpm]
texlive-gnu-freefont [platform:rpm]
+texlive-tex-gyre [platform:rpm]
latexmk [platform:rpm]
texlive-latex-recommended [platform:dpkg]
texlive-fonts-recommended [platform:dpkg]
+tex-gyre [platform:dpkg]
texlive-latex-extra [platform:dpkg]
texlive-luatex [platform:dpkg]
latexmk [platform:dpkg]
diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt
index 5420e2717e..844451fd8a 100644
--- a/doc/_static/conf.py.txt
+++ b/doc/_static/conf.py.txt
@@ -43,7 +43,7 @@ source_suffix = '.rst'
# source_encoding = 'utf-8-sig'
# The master toctree document.
-master_doc = 'index'
+root_doc = 'index'
# General information about the project.
project = u'test'
@@ -252,7 +252,7 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- (master_doc, 'test.tex', u'test Documentation',
+ (root_doc, 'test.tex', u'test Documentation',
u'test', 'manual'),
]
@@ -283,7 +283,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- (master_doc, 'test', u'test Documentation',
+ (root_doc, 'test', u'test Documentation',
[author], 1)
]
@@ -298,7 +298,7 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- (master_doc, 'test', u'test Documentation',
+ (root_doc, 'test', u'test Documentation',
author, 'test', 'One line description of project.',
'Miscellaneous'),
]
diff --git a/doc/conf.py b/doc/conf.py
index a3d2f5f12d..ddf68de051 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -9,7 +9,7 @@
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram']
-master_doc = 'contents'
+root_doc = 'contents'
templates_path = ['_templates']
exclude_patterns = ['_build']
@@ -59,17 +59,6 @@
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': r'''
\PassOptionsToPackage{svgnames}{xcolor}
\PassOptionsToPackage{bookmarksdepth=3}{hyperref}% depth of pdf bookmarks
@@ -79,7 +68,6 @@
\setcounter{tocdepth}{3}% depth of what is kept from toc file
\setcounter{secnumdepth}{1}% depth of section numbering
''',
- 'fvset': '\\fvset{fontsize=auto}',
# fix missing index entry due to RTD doing only once pdflatex after makeindex
'printindex': r'''
\IfFileExists{\jobname.ind}
@@ -91,6 +79,7 @@
latex_use_xindy = True
autodoc_member_order = 'groupwise'
+autosummary_generate = False
todo_include_todos = True
extlinks = {'duref': ('http://docutils.sourceforge.net/docs/ref/rst/'
'restructuredtext.html#%s', ''),
diff --git a/doc/development/tutorials/autodoc_ext.rst b/doc/development/tutorials/autodoc_ext.rst
new file mode 100644
index 0000000000..d8905710c6
--- /dev/null
+++ b/doc/development/tutorials/autodoc_ext.rst
@@ -0,0 +1,142 @@
+.. _autodoc_ext_tutorial:
+
+Developing autodoc extension for IntEnum
+========================================
+
+The objective of this tutorial is to create an extension that adds
+support for new type for autodoc. This autodoc extension will format
+the ``IntEnum`` class from Python standard library. (module ``enum``)
+
+Overview
+--------
+
+We want the extension that will create auto-documentation for IntEnum.
+``IntEnum`` is the integer enum class from standard library ``enum`` module.
+
+Currently this class has no special auto documentation behavior.
+
+We want to add following to autodoc:
+
+* A new ``autointenum`` directive that will document the ``IntEnum`` class.
+* The generated documentation will have all the enum possible values
+ with names.
+* The ``autointenum`` directive will have an option ``:hex:`` which will
+ cause the integers be printed in hexadecimal form.
+
+
+Prerequisites
+-------------
+
+We need the same setup as in :doc:`the previous extensions `. This time,
+we will be putting out extension in a file called :file:`autodoc_intenum.py`.
+The :file:`my_enums.py` will contain the sample enums we will document.
+
+Here is an example of the folder structure you might obtain:
+
+.. code-block:: text
+
+ └── source
+ ├── _ext
+ │ └── autodoc_intenum.py
+ ├── conf.py
+ ├── index.rst
+ └── my_enums.py
+
+
+Writing the extension
+---------------------
+
+Start with ``setup`` function for the extension.
+
+.. literalinclude:: examples/autodoc_intenum.py
+ :language: python
+ :linenos:
+ :pyobject: setup
+
+
+The :meth:`~Sphinx.setup_extension` method will pull the autodoc extension
+because our new extension depends on autodoc. :meth:`~Sphinx.add_autodocumenter`
+is the method that registers our new auto documenter class.
+
+We want to import certain objects from the autodoc extension:
+
+.. literalinclude:: examples/autodoc_intenum.py
+ :language: python
+ :linenos:
+ :lines: 1-7
+
+
+There are several different documenter classes such as ``MethodDocumenter``
+or ``AttributeDocumenter`` available in the autodoc extension but
+our new class is the subclass of ``ClassDocumenter`` which a
+documenter class used by autodoc to document classes.
+
+This is the definition of our new the auto-documenter class:
+
+.. literalinclude:: examples/autodoc_intenum.py
+ :language: python
+ :linenos:
+ :pyobject: IntEnumDocumenter
+
+
+Important attributes of the new class:
+
+**objtype**
+ This attribute determines the ``auto`` directive name. In
+ this case the auto directive will be ``autointenum``.
+
+**directivetype**
+ This attribute sets the generated directive name. In
+ this example the generated directive will be ``.. :py:class::``.
+
+**priority**
+ the larger the number the higher is the priority. We want our
+ documenter be higher priority than the parent.
+
+**option_spec**
+ option specifications. We copy the parent class options and
+ add a new option *hex*.
+
+
+Overridden members:
+
+**can_document_member**
+ This member is important to override. It should
+ return *True* when the passed object can be documented by this class.
+
+**add_directive_header**
+ This method generates the directive header. We add
+ **:final:** directive option. Remember to call **super** or no directive
+ will be generated.
+
+**add_content**
+ This method generates the body of the class documentation.
+ After calling the super method we generate lines for enum description.
+
+
+Using the extension
+-------------------
+
+You can now use the new autodoc directive to document any ``IntEnum``.
+
+For example, you have the following ``IntEnum``:
+
+.. code-block:: python
+ :caption: my_enums.py
+
+ class Colors(IntEnum):
+ """Colors enumerator"""
+ NONE = 0
+ RED = 1
+ GREEN = 2
+ BLUE = 3
+
+
+This will be the documentation file with auto-documentation directive:
+
+.. code-block:: rst
+ :caption: index.rst
+
+ .. autointenum:: my_enums.Colors
+
+
diff --git a/doc/development/tutorials/examples/autodoc_intenum.py b/doc/development/tutorials/examples/autodoc_intenum.py
new file mode 100644
index 0000000000..7fb85d0662
--- /dev/null
+++ b/doc/development/tutorials/examples/autodoc_intenum.py
@@ -0,0 +1,52 @@
+from enum import IntEnum
+from typing import Any, Optional
+
+from docutils.statemachine import StringList
+
+from sphinx.application import Sphinx
+from sphinx.ext.autodoc import ClassDocumenter, bool_option
+
+
+class IntEnumDocumenter(ClassDocumenter):
+ objtype = 'intenum'
+ directivetype = 'class'
+ priority = 10 + ClassDocumenter.priority
+ option_spec = dict(ClassDocumenter.option_spec)
+ option_spec['hex'] = bool_option
+
+ @classmethod
+ def can_document_member(cls,
+ member: Any, membername: str,
+ isattr: bool, parent: Any) -> bool:
+ return isinstance(member, IntEnum)
+
+ def add_directive_header(self, sig: str) -> None:
+ super().add_directive_header(sig)
+ self.add_line(' :final:', self.get_sourcename())
+
+ def add_content(self,
+ more_content: Optional[StringList],
+ no_docstring: bool = False
+ ) -> None:
+
+ super().add_content(more_content, no_docstring)
+
+ source_name = self.get_sourcename()
+ enum_object: IntEnum = self.object
+ use_hex = self.options.hex
+ self.add_line('', source_name)
+
+ for enum_value in enum_object:
+ the_value_name = enum_value.name
+ the_value_value = enum_value.value
+ if use_hex:
+ the_value_value = hex(the_value_value)
+
+ self.add_line(
+ f"**{the_value_name}**: {the_value_value}", source_name)
+ self.add_line('', source_name)
+
+
+def setup(app: Sphinx) -> None:
+ app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
+ app.add_autodocumenter(IntEnumDocumenter)
diff --git a/doc/development/tutorials/index.rst b/doc/development/tutorials/index.rst
index be126b3ca4..a7eee48991 100644
--- a/doc/development/tutorials/index.rst
+++ b/doc/development/tutorials/index.rst
@@ -13,3 +13,5 @@ Refer to the following tutorials to get started with extension development.
helloworld
todo
recipe
+ autodoc_ext
+
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
index 4585df9493..9949910346 100644
--- a/doc/extdev/appapi.rst
+++ b/doc/extdev/appapi.rst
@@ -167,26 +167,33 @@ type for that event::
4. event.env-before-read-docs(app, env, docnames)
for docname in docnames:
- 5. event.env-purge-doc(app, env, docname)
+ 5. event.env-purge-doc(app, env, docname)
+
if doc changed and not removed:
6. source-read(app, docname, source)
- 7. run source parsers: text -> docutils.document (parsers can be added with the app.add_source_parser() API)
- 8. apply transforms (by priority): docutils.document -> docutils.document
- - event.doctree-read(app, doctree) is called in the middly of transforms,
+ 7. run source parsers: text -> docutils.document
+ - parsers can be added with the app.add_source_parser() API
+ 8. apply transforms based on priority: docutils.document -> docutils.document
+ - event.doctree-read(app, doctree) is called in the middle of transforms,
transforms come before/after this event depending on their priority.
- 9. (if running in parallel mode, for each process) event.env-merged-info(app, env, docnames, other)
+
+ 9. event.env-merged-info(app, env, docnames, other)
+ - if running in parallel mode, this event will be emitted for each process
+
10. event.env-updated(app, env)
11. event.env-get-updated(app, env)
12. event.env-check-consistency(app, env)
# The updated-docs list can be builder dependent, but generally includes all new/changed documents,
# plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
- # For builders that output a single page, they are first joined into a single doctree before post-transforms/doctree-resolved
+ # For builders that output a single page, they are first joined into a single doctree before post-transforms
+ # or the doctree-resolved event is emitted
for docname in updated-docs:
13. apply post-transforms (by priority): docutils.document -> docutils.document
14. event.doctree-resolved(app, doctree, docname)
- - (for any reference node that fails to resolve) event.missing-reference(env, node, contnode)
- - (for any reference node that fails to resolve) event.warn-missing-reference(domain, node)
+ - In the event that any reference nodes fail to resolve, the following may emit:
+ - event.missing-reference(env, node, contnode)
+ - event.warn-missing-reference(domain, node)
15. Generate output files
16. event.build-finished(app, exception)
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index ccf1e79da1..96bc84ff3b 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -22,6 +22,56 @@ The following is a list of deprecated interfaces.
- (will be) Removed
- Alternatives
+ * - ``favicon`` variable in HTML templates
+ - 4.0
+ - TBD
+ - ``favicon_url``
+
+ * - ``logo`` variable in HTML templates
+ - 4.0
+ - TBD
+ - ``logo_url``
+
+ * - ``sphinx.directives.patches.ListTable``
+ - 4.0
+ - 6.0
+ - ``docutils.parsers.rst.diretives.tables.ListSVTable``
+
+ * - ``sphinx.directives.patches.RSTTable``
+ - 4.0
+ - 6.0
+ - ``docutils.parsers.rst.diretives.tables.RSTTable``
+
+ * - ``sphinx.registry.SphinxComponentRegistry.get_source_input()``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.registry.SphinxComponentRegistry.source_inputs``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.transforms.FigureAligner``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.util.pycompat.convert_with_2to3()``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.util.pycompat.execfile_()``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.util.smartypants``
+ - 4.0
+ - 6.0
+ - ``docutils.utils.smartyquotes``
+
* - pending_xref node for viewcode extension
- 3.5
- 5.0
diff --git a/doc/extdev/nodes.rst b/doc/extdev/nodes.rst
index 5d8272eae2..3976de4c70 100644
--- a/doc/extdev/nodes.rst
+++ b/doc/extdev/nodes.rst
@@ -37,8 +37,8 @@ New inline nodes
.. autoclass:: index
.. autoclass:: pending_xref
+.. autoclass:: pending_xref_condition
.. autoclass:: literal_emphasis
-.. autoclass:: abbreviation
.. autoclass:: download_reference
Special nodes
diff --git a/doc/latex.rst b/doc/latex.rst
index 4467319645..b736c56ef0 100644
--- a/doc/latex.rst
+++ b/doc/latex.rst
@@ -139,57 +139,33 @@ Keys that you may want to override include:
``babel``, not ``polyglossia``.
``'fontpkg'``
- Font package inclusion. The default of ``'\\usepackage{times}'`` uses Times
- for text, Helvetica for sans serif and Courier for monospace.
-
- 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}
-
- 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, these are the
- ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and (with the above
- choice of fonts) the ``cm-super`` (or ``cm-super-minimal``) packages.
-
- 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 necessary to install the much larger ``texlive-fonts-extra``
- package.
-
- ``'platex'`` (Japanese documents) engine supports individual Cyrillic and
- Greek letters with no need of extra user set-up.
-
- Default: ``'\\usepackage{times}'`` (or ``''`` when using a Cyrillic script)
+ Font package inclusion. The default is::
+
+ r"""\usepackage{tgtermes}
+ \usepackage{tgheros}
+ \renewcommand\ttdefault{txtt}
+ """
+
+ For ``'xelatex'`` and ``'lualatex'`` however the default is to use
+ the GNU FreeFont.
.. versionchanged:: 1.2
Defaults to ``''`` when the :confval:`language` uses the Cyrillic
script.
.. versionchanged:: 2.0
- Added support for individual Greek and Cyrillic letters:
+ Incorporates some font substitution commands to help support occasional
+ Greek or Cyrillic in a document using ``'pdflatex'`` engine.
+
+ .. versionchanged:: 4.0.0
+ - The font substitution commands added at ``2.0`` have been moved
+ to the ``'fontsubstitution'`` key, as their presence here made
+ it complicated for user to customize the value of ``'fontpkg'``.
+ - The default font setting has changed: it still uses Times and
+ Helvetica clones for serif and sans serif, but via better, more
+ complete TeX fonts and associated LaTeX packages. The
+ monospace font has been changed to better match the Times clone.
+
``'fncychap'``
Inclusion of the "fncychap" package (which makes fancy chapter titles),
@@ -320,37 +296,28 @@ Keys that don't need to be overridden unless in special cases are:
.. versionadded:: 1.2
``'fontenc'``
- "fontenc" package inclusion.
+ Customize this from its default ``'\\usepackage[T1]{fontenc}'`` to:
- 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:
+ - ``'\\usepackage[X2,T1]{fontenc}'`` if you need occasional
+ Cyrillic letters (физика частиц),
- .. code-block:: latex
+ - ``'\\usepackage[LGR,T1]{fontenc}'`` if you need occasional
+ Greek letters (Σωματιδιακή φυσική).
- r'\usepackage[LGR,X2,T1]{fontenc}'
+ Use ``[LGR,X2,T1]`` rather if both are needed.
.. attention::
- If Greek is main language, do not use this key. Since Sphinx 2.2.1,
- ``xelatex`` will be used automatically as :confval:`latex_engine`.
- Formerly, Sphinx did not support producing PDF via LaTeX with Greek as
- main language.
+ - Do not use this key for a :confval:`latex_engine` other than
+ ``'pdflatex'``.
- 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.
+ - If Greek is main language, do not use this key. Since Sphinx 2.2.1,
+ ``xelatex`` will be used automatically as :confval:`latex_engine`.
- 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.
-
- Default: ``'\\usepackage[T1]{fontenc}'``
+ - The TeX installation may need some extra packages. For example,
+ on Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
+ are needed for ``LGR`` to work. And ``texlive-lang-cyrillic`` and
+ ``cm-super`` are needed for support of Cyrillic.
.. versionchanged:: 1.5
Defaults to ``'\\usepackage{fontspec}'`` when
@@ -367,32 +334,37 @@ Keys that don't need to be overridden unless in special cases are:
.. 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'``).
+ occasional Greek or Cyrillic letters (``'pdflatex'``).
.. versionchanged:: 2.3.0
- ``'xelatex'`` also executes
+ ``'xelatex'`` executes
``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid
contractions of ``--`` into en-dash or transforms of straight quotes
into curly ones in PDF (in non-literal text paragraphs) despite
:confval:`smartquotes` being set to ``False``.
-``'textgreek'``
- 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``.
+``'fontsubstitution'``
+ Ignored if ``'fontenc'`` was not configured to use ``LGR`` or ``X2`` (or
+ ``T2A``). In case ``'fontpkg'`` key is configured for usage with some
+ TeX fonts known to be available in the ``LGR`` or ``X2`` encodings, set
+ this one to be the empty string. Else leave to its default.
- .. hint::
+ Ignored with :confval:`latex_engine` other than ``'pdflatex'``.
+
+ .. versionadded:: 4.0.0
+
+``'textgreek'``
+ For the support of occasional Greek letters.
- 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`.
+ It is ignored with ``'platex'``, ``'xelatex'`` or ``'lualatex'`` as
+ :confval:`latex_engine` and defaults to either the empty string or
+ to ``'\\usepackage{textalpha}'`` for ``'pdflatex'`` depending on
+ whether the ``'fontenc'`` key was used with ``LGR`` or not. Only
+ expert LaTeX users may want to customize this key.
- With ``'platex'`` (Japanese), ``'xelatex'`` or ``'lualatex'``, this
- key is ignored.
+ It can also be used as ``r'\usepackage{textalpha,alphabeta}'`` to let
+ ``'pdflatex'`` support Greek Unicode input in :rst:dir:`math` context.
+ For example ``:math:`α``` (U+03B1) will render as :math:`\alpha`.
Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not
include the ``LGR`` option.
@@ -517,19 +489,25 @@ Keys that don't need to be overridden unless in special cases are:
Default: ``'\\printindex'``
``'fvset'``
- Customization of ``fancyvrb`` LaTeX package. The default value of
- ``'\\fvset{fontsize=\\small}'`` is used 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.
+ Customization of ``fancyvrb`` LaTeX package.
- Default: ``'\\fvset{fontsize=\\small}'``
+ The default value is ``'\\fvset{fontsize=auto}'`` which means that the
+ font size will adjust correctly if a code-block ends up in a footnote.
+ You may need to modify this if you use custom fonts:
+ ``'\\fvset{fontsize=\\small}'`` if the monospace font is Courier-like.
+
+ Default: ``'\\fvset{fontsize=auto}'``
.. 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}``).
+ For ``'xelatex'`` and ``'lualatex'`` defaults to
+ ``'\\fvset{fontsize=\\small}'`` as this
+ is adapted to the relative widths of the FreeFont family.
+
+ .. versionchanged:: 4.0.0
+ Changed default for ``'pdflatex'``. Previously it was using
+ ``'\\fvset{fontsize=\\small}'``.
Keys that are set by other options and therefore should not be overridden are:
@@ -917,9 +895,36 @@ macros may be significant.
LaTeX macros and environments
-----------------------------
-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.
+The "LaTeX package" file :file:`sphinx.sty` loads various components
+providing support macros (aka commands), and environments, which are used in
+the mark-up produced on output from the ``latex`` builder, before conversion
+to ``pdf`` via the LaTeX toolchain. Also the "LaTeX class" files
+:file:`sphinxhowto.cls` and :file:`sphinxmanual.cls` define or customize some
+environments. All of these files can be found in the latex build repertory.
+
+Some of these provide facilities not available from pre-existing LaTeX
+packages and work around LaTeX limitations with lists, table cells, verbatim
+rendering, footnotes, etc...
+
+Others simply define macros with public names to make overwriting their
+defaults easy via user-added contents to the preamble. We will survey most of
+those public names here, but defaults have to be looked at in their respective
+definition files.
+
+.. hint::
+
+ Sphinx LaTeX support code is split across multiple smaller-sized files.
+ Rather than adding code to the preamble via
+ `latex_elements `_\ [``'preamble'``] it is
+ also possible to replace entirely one of the component files of Sphinx
+ LaTeX code with a custom version, simply by including a modified copy in
+ the project source and adding the filename to the
+ :confval:`latex_additional_files` list. Check the LaTeX build repertory
+ for the filenames and contents.
+
+.. versionchanged:: 4.0.0
+ split of :file:`sphinx.sty` into multiple smaller units, to facilitate
+ customization of many aspects simultaneously.
.. _latex-macros:
diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst
index 725d2f1692..3ce5b45233 100644
--- a/doc/man/sphinx-apidoc.rst
+++ b/doc/man/sphinx-apidoc.rst
@@ -145,7 +145,7 @@ These options are used when :option:`--full` is specified:
* ``module.rst_t``
* ``package.rst_t``
* ``toc.rst_t``
- * ``master_doc.rst_t``
+ * ``root_doc.rst_t``
* ``conf.py_t``
* ``Makefile_t``
* ``Makefile.new_t``
diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst
index 520a420ce7..16fc665605 100644
--- a/doc/man/sphinx-quickstart.rst
+++ b/doc/man/sphinx-quickstart.rst
@@ -72,7 +72,7 @@ Options
.. option:: --master=MASTER
- Master document name. (see :confval:`master_doc`).
+ Master document name. (see :confval:`root_doc`).
.. rubric:: Extension Options
@@ -149,7 +149,7 @@ Options
sphinx project files generated by quickstart. Following Jinja2 template
files are allowed:
- * ``master_doc.rst_t``
+ * ``root_doc.rst_t``
* ``conf.py_t``
* ``Makefile_t``
* ``Makefile.new_t``
diff --git a/doc/templating.rst b/doc/templating.rst
index 548f8b8d93..61b714bfa3 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -274,7 +274,19 @@ in the future.
.. data:: favicon
- The path to the HTML favicon in the static path, or ``''``.
+ The path to the HTML favicon in the static path, or URL to the favicon, or
+ ``''``.
+
+ .. deprecated:: 4.0
+
+ Recommend to use ``favicon_url`` instead.
+
+.. data:: favicon_url
+
+ The relative path to the HTML favicon image from the current document, or
+ URL to the favicon, or ``''``.
+
+ .. versionadded:: 4.0
.. data:: file_suffix
@@ -297,11 +309,35 @@ in the future.
.. data:: logo
- The path to the HTML logo image in the static path, or ``''``.
+ The path to the HTML logo image in the static path, or URL to the logo, or
+ ``''``.
+
+ .. deprecated:: 4.0
+
+ Recommend to use ``logo_url`` instead.
+
+.. data:: logo_url
+
+ The relative path to the HTML logo image from the current document, or URL
+ to the logo, or ``''``.
+
+ .. versionadded:: 4.0
.. data:: master_doc
- The value of :confval:`master_doc`, for usage with :func:`pathto`.
+ Same as :data:`root_doc`.
+
+ .. versionchanged:: 4.0
+
+ Renamed to ``root_doc``.
+
+.. data:: root_doc
+
+ The value of :confval:`root_doc`, for usage with :func:`pathto`.
+
+ .. versionchanged:: 4.0
+
+ Renamed from ``master_doc``.
.. data:: pagename
diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst
index 67d5e10e56..03b77fb6b3 100644
--- a/doc/usage/advanced/intl.rst
+++ b/doc/usage/advanced/intl.rst
@@ -306,7 +306,7 @@ Contributing to Sphinx reference translation
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.
+There is a `sphinx translation page`_ for Sphinx (master) documentation.
1. Login to transifex_ service.
2. Go to `sphinx translation page`_.
@@ -314,6 +314,8 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
4. Wait acceptance by transifex sphinx translation maintainers.
5. (After acceptance) Translate on transifex.
+Detail is here: https://docs.transifex.com/getting-started-1/translators
+
.. rubric:: Footnotes
.. [1] See the `GNU gettext utilities
diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst
index c45a8062fb..74853fee97 100644
--- a/doc/usage/builders/index.rst
+++ b/doc/usage/builders/index.rst
@@ -179,6 +179,7 @@ The builder's "name" must be given to the **-b** command-line option of
* ``texlive-latex-recommended``
* ``texlive-fonts-recommended``
+ * ``tex-gyre`` (if :confval:`latex_engine` is ``'pdflatex'``)
* ``texlive-latex-extra``
* ``latexmk`` (this is a Sphinx requirement on GNU/Linux and MacOS X
for functioning of ``make latexpdf``)
@@ -186,17 +187,14 @@ The builder's "name" must be given to the **-b** command-line option of
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``.
+ * ``texlive-lang-cyrillic`` for Cyrillic (even individual letters), and,
+ ``cm-super`` or ``cm-super-minimal`` (if default fonts),
+ * ``texlive-lang-greek`` for Greek (even individual letters), and,
+ ``cm-super`` or ``cm-super-minimal`` (if default fonts),
+ * ``texlive-xetex`` if :confval:`latex_engine` is ``'xelatex'``,
+ * ``texlive-luatex`` if :confval:`latex_engine` is ``'lualatex'``,
+ * ``fonts-freefont-otf`` if :confval:`latex_engine` is ``'xelatex'``
+ or ``'lualatex'``.
The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution
is based on a TeXLive 2015 snapshot dated March 2016.
@@ -207,6 +205,9 @@ The builder's "name" must be given to the **-b** command-line option of
.. versionchanged:: 2.0
Formerly, testing had been done on Ubuntu trusty (TeXLive 2013).
+ .. versionchanged:: 4.0.0
+ TeX Gyre fonts dependency for the default LaTeX font configuration.
+
.. note::
Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows). This
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index c2250eb7d9..989ce8737e 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -183,11 +183,20 @@ General configuration
.. confval:: master_doc
- The document name of the "master" document, that is, the document that
+ Same as :confval:`root_doc`.
+
+ .. versionchanged:: 4.0
+ Renamed ``master_doc`` to ``master_doc``.
+
+.. confval:: root_doc
+
+ The document name of the "root" document, that is, the document that
contains the root :rst:dir:`toctree` directive. Default is ``'index'``.
.. versionchanged:: 2.0
The default is changed to ``'index'`` from ``'contents'``.
+ .. versionchanged:: 4.0
+ Renamed ``master_doc`` from ``master_doc``.
.. confval:: exclude_patterns
@@ -479,11 +488,10 @@ General configuration
.. confval:: smartquotes_action
- This string, for use with Docutils ``0.14`` or later, customizes the Smart
- Quotes transform. See the file :file:`smartquotes.py` at the `Docutils
- repository`__ for details. The default ``'qDe'`` educates normal **q**\
- uote characters ``"``, ``'``, em- and en-**D**\ ashes ``---``, ``--``, and
- **e**\ llipses ``...``.
+ This string customizes the Smart Quotes transform. See the file
+ :file:`smartquotes.py` at the `Docutils repository`__ for details. The
+ default ``'qDe'`` educates normal **q**\ uote characters ``"``, ``'``,
+ em- and en-**D**\ ashes ``---``, ``--``, and **e**\ llipses ``...``.
.. versionadded:: 1.6.6
@@ -834,13 +842,16 @@ documentation on :ref:`intl` for details.
:literal-block: literal blocks (``::`` annotation and ``code-block`` directive)
:doctest-block: doctest block
:raw: raw content
- :image: image/figure uri and alt
+ :image: image/figure uri
For example: ``gettext_additional_targets = ['literal-block', 'image']``.
The default is ``[]``.
.. versionadded:: 1.3
+ .. versionchanged:: 4.0
+
+ The alt text for image is translated by default.
.. confval:: figure_language_filename
@@ -970,10 +981,15 @@ that use Sphinx's HTMLWriter class.
The style of line numbers for code-blocks.
- * ``'table'`` -- display line numbers using ``
`` tag (default)
- * ``'inline'`` -- display line numbers using ```` tag
+ * ``'table'`` -- display line numbers using ``
`` tag
+ * ``'inline'`` -- display line numbers using ```` tag (default)
.. versionadded:: 3.2
+ .. versionchanged:: 4.0
+
+ It defaults to ``'inline'``.
+
+ .. deprecated:: 4.0
.. confval:: html_context
@@ -986,26 +1002,32 @@ that use Sphinx's HTMLWriter class.
.. confval:: html_logo
If given, this must be the name of an image file (path relative to the
- :term:`configuration directory`) that is the logo of the docs. It is placed
- at the top of the sidebar; its width should therefore not exceed 200 pixels.
- Default: ``None``.
+ :term:`configuration directory`) that is the logo of the docs, or URL that
+ points an image file for the logo. It is placed at the top of the sidebar;
+ its width should therefore not exceed 200 pixels. Default: ``None``.
.. versionadded:: 0.4.1
The image file will be copied to the ``_static`` directory of the output
HTML, but only if the file does not already exist there.
+ .. versionchanged:: 4.0
+ Also accepts the URL for the logo file.
+
.. confval:: html_favicon
If given, this must be the name of an image file (path relative to the
- :term:`configuration directory`) that is the favicon of the docs. Modern
- browsers use this as the icon for tabs, windows and bookmarks. It should
- be a Windows-style icon file (``.ico``), which is 16x16 or 32x32
- pixels large. Default: ``None``.
+ :term:`configuration directory`) that is the favicon of the docs, or URL that
+ points an image file for the favicon. Modern browsers use this as the icon
+ for tabs, windows and bookmarks. It should be a Windows-style icon file
+ (``.ico``), which is 16x16 or 32x32 pixels large. Default: ``None``.
.. versionadded:: 0.4
The image file will be copied to the ``_static`` directory of the output
HTML, but only if the file does not already exist there.
+ .. versionchanged:: 4.0
+ Also accepts the URL for the favicon.
+
.. confval:: html_css_files
A list of CSS files. The entry must be a *filename* string or a tuple
@@ -1479,8 +1501,7 @@ that use Sphinx's HTMLWriter class.
.. confval:: html_experimental_html5_writer
- Output is processed with HTML5 writer. This feature needs docutils 0.13 or
- newer. Default is ``False``.
+ Output is processed with HTML5 writer. Default is ``False``.
.. versionadded:: 1.6
@@ -1957,8 +1978,8 @@ These options influence LaTeX output.
* ``'pdflatex'`` -- PDFLaTeX (default)
* ``'xelatex'`` -- XeLaTeX
* ``'lualatex'`` -- LuaLaTeX
- * ``'platex'`` -- pLaTeX (default if :confval:`language` is ``'ja'``)
- * ``'uplatex'`` -- upLaTeX (experimental)
+ * ``'platex'`` -- pLaTeX
+ * ``'uplatex'`` -- upLaTeX (default if :confval:`language` is ``'ja'``)
``'pdflatex'``\ 's support for Unicode characters is limited.
@@ -1988,6 +2009,10 @@ These options influence LaTeX output.
Add ``uplatex`` support.
+ .. versionchanged:: 4.0
+
+ ``uplatex`` becomes the default setting of Japanese documents.
+
Contrarily to :ref:`MathJaX math rendering in HTML output `,
LaTeX requires some extra configuration to support Unicode literals in
:rst:dir:`math`: the only comprehensive solution (as far as we know) is to
@@ -2007,8 +2032,8 @@ These options influence LaTeX output.
*startdocname*
String that specifies the :term:`document name` of the LaTeX file's master
document. All documents referenced by the *startdoc* document in TOC trees
- will be included in the LaTeX file. (If you want to use the default master
- document for your LaTeX build, provide your :confval:`master_doc` here.)
+ will be included in the LaTeX file. (If you want to use the default root
+ document for your LaTeX build, provide your :confval:`root_doc` here.)
*targetname*
File name of the LaTeX file in the output directory.
@@ -2277,7 +2302,7 @@ These options influence manual page output.
String that specifies the :term:`document name` of the manual page's master
document. All documents referenced by the *startdoc* document in TOC trees
will be included in the manual file. (If you want to use the default
- master document for your manual pages build, use your :confval:`master_doc`
+ root document for your manual pages build, use your :confval:`root_doc`
here.)
*name*
@@ -2307,10 +2332,12 @@ These options influence manual page output.
.. confval:: man_make_section_directory
- If true, make a section directory on build man page. Default is False.
+ If true, make a section directory on build man page. Default is True.
.. versionadded:: 3.3
+ .. versionchanged:: 4.0
+ The default is changed to ``False`` from ``True``.
.. _texinfo-options:
@@ -2331,7 +2358,7 @@ These options influence Texinfo output.
master document. All documents referenced by the *startdoc* document in
TOC trees will be included in the Texinfo file. (If you want to use the
default master document for your Texinfo build, provide your
- :confval:`master_doc` here.)
+ :confval:`root_doc` here.)
*targetname*
File name (no extension) of the Texinfo file in the output directory.
@@ -2687,6 +2714,17 @@ Options for the C++ domain
.. versionadded:: 1.5
+Options for the Python domain
+-----------------------------
+
+.. confval:: python_use_unqualified_type_names
+
+ If true, suppress the module name of the python reference if it can be
+ resolved. The default is ``False``.
+
+ .. versionadded:: 4.0
+
+ .. note:: This configuration is still in experimental
Example of configuration file
=============================
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
index a07042781e..034c86e113 100644
--- a/doc/usage/extensions/autodoc.rst
+++ b/doc/usage/extensions/autodoc.rst
@@ -89,33 +89,96 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
Boil the noodle *time* minutes.
- **Options and advanced usage**
+ .. rubric:: Options
+
+ .. rst:directive:option:: members
+ :type: no value or comma separated list
+
+ If set, autodoc will generate document for the members of the target
+ module, class or exception.
- * If you want to automatically document members, there's a ``members``
- option::
+ For example::
.. automodule:: noodle
:members:
- will document all module members (recursively), and ::
+ will document all module members (recursively), and ::
.. autoclass:: Noodle
:members:
- will document all non-private member functions and properties (that is,
- those whose name doesn't start with ``_``).
+ will document all class member methods and properties.
- For modules, ``__all__`` will be respected when looking for members unless
- you give the ``ignore-module-all`` flag option. Without
- ``ignore-module-all``, the order of the members will also be the order in
- ``__all__``.
+ By default, autodoc will not generate document for the members that are
+ private, not having docstrings, inherited from super class, or special
+ members.
- You can also give an explicit list of members; only these will then be
- documented::
+ For modules, ``__all__`` will be respected when looking for members unless
+ you give the ``ignore-module-all`` flag option. Without
+ ``ignore-module-all``, the order of the members will also be the order in
+ ``__all__``.
+
+ You can also give an explicit list of members; only these will then be
+ documented::
.. autoclass:: Noodle
:members: eat, slurp
+ .. rst:directive:option:: undoc-members
+ :type: no value
+
+ If set, autodoc will also generate document for the members not having
+ docstrings::
+
+ .. automodule:: noodle
+ :members:
+ :undoc-members:
+
+ .. rst:directive:option:: private-members
+ :type: no value or comma separated list
+
+ If set, autodoc will also generate document for the private members
+ (that is, those named like ``_private`` or ``__private``)::
+
+ .. automodule:: noodle
+ :members:
+ :private-members:
+
+ It can also take an explicit list of member names to be documented as
+ arguments::
+
+ .. automodule:: noodle
+ :members:
+ :private-members: _spicy, _garlickly
+
+ .. versionadded:: 1.1
+ .. versionchanged:: 3.2
+ The option can now take arguments.
+
+ .. rst:directive:option:: special-members
+ :type: no value or comma separated list
+
+ If set, autodoc will also generate document for the special members
+ (that is, those named like ``__special__``)::
+
+ .. autoclass:: my.Class
+ :members:
+ :special-members:
+
+ It can also take an explicit list of member names to be documented as
+ arguments::
+
+ .. autoclass:: my.Class
+ :members:
+ :special-members: __init__, __name__
+
+ .. versionadded:: 1.1
+
+ .. versionchanged:: 1.2
+ The option can now take arguments
+
+ **Options and advanced usage**
+
* If you want to make the ``members`` option (or other options described
below) the default, see :confval:`autodoc_default_options`.
@@ -139,31 +202,6 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
.. versionchanged:: 3.5
The default options can be overridden or extended temporarily.
- * Members without docstrings will be left out, unless you give the
- ``undoc-members`` flag option::
-
- .. automodule:: noodle
- :members:
- :undoc-members:
-
- * "Private" members (that is, those named like ``_private`` or ``__private``)
- will be included if the ``private-members`` flag option is given::
-
- .. automodule:: noodle
- :members:
- :private-members:
-
- It can also take an explicit list of member names to be documented as
- arguments::
-
- .. automodule:: noodle
- :members:
- :private-members: _spicy, _garlickly
-
- .. versionadded:: 1.1
- .. versionchanged:: 3.2
- The option can now take arguments.
-
* autodoc considers a member private if its docstring contains
``:meta private:`` in its :ref:`info-field-lists`.
For example:
@@ -203,21 +241,6 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
.. versionadded:: 3.5
- * Python "special" members (that is, those named like ``__special__``) will
- be included if the ``special-members`` flag option is given::
-
- .. autoclass:: my.Class
- :members:
- :private-members:
- :special-members:
-
- would document both "private" and "special" members of the class.
-
- .. versionadded:: 1.1
-
- .. versionchanged:: 1.2
- The option can now take arguments, i.e. the special members to document.
-
* For classes and exceptions, members inherited from base classes will be
left out when documenting all members, unless you give the
``inherited-members`` option, in addition to ``members``::
@@ -586,6 +609,16 @@ There are also config values that you can set:
.. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
.. versionadded:: 3.3
+.. confval:: autodoc_preserve_defaults
+
+ If True, the default argument values of functions will be not evaluated on
+ generating document. It preserves them as is in the source code.
+
+ .. versionadded:: 4.0
+
+ Added as an experimental feature. This will be integrated into autodoc core
+ in the future.
+
.. confval:: autodoc_warningiserror
This value controls the behavior of :option:`sphinx-build -W` during
@@ -597,7 +630,7 @@ There are also config values that you can set:
This value controls the docstrings inheritance.
If set to True the docstring for classes or methods, if not explicitly set,
- is inherited form parents.
+ is inherited from parents.
The default is ``True``.
diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst
index 03ea7548e2..28f207de7f 100644
--- a/doc/usage/extensions/autosummary.rst
+++ b/doc/usage/extensions/autosummary.rst
@@ -19,11 +19,13 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
that contain links to the documented items, and short summary blurbs
extracted from their docstrings.
-2. Optionally, the convenience script :program:`sphinx-autogen` or the new
- :confval:`autosummary_generate` config value can be used to generate short
- "stub" files for the entries listed in the :rst:dir:`autosummary` directives.
- These files by default contain only the corresponding
- :mod:`sphinx.ext.autodoc` directive, but can be customized with templates.
+2. A :rst:dir:`autosummary` directive also generates short "stub" files for the
+ entries listed in its content. These files by default contain only the
+ corresponding :mod:`sphinx.ext.autodoc` directive, but can be customized with
+ templates.
+
+ The :program:`sphinx-autogen` script is also able to generate "stub" files
+ from command line.
.. rst:directive:: autosummary
@@ -161,7 +163,7 @@ also use these config values:
.. confval:: autosummary_generate
Boolean indicating whether to scan all found documents for autosummary
- directives, and to generate stub pages for each. It is disabled by default.
+ directives, and to generate stub pages for each. It is enabled by default.
Can also be a list of documents for which stub pages should be generated.
@@ -173,6 +175,10 @@ also use these config values:
Emits :event:`autodoc-skip-member` event as :mod:`~sphinx.ext.autodoc`
does.
+ .. versionchanged:: 4.0
+
+ Enabled by default.
+
.. confval:: autosummary_generate_overwrite
If true, autosummary overwrites existing files by generated stub pages.
diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst
index 780e57ee29..655364767b 100644
--- a/doc/usage/extensions/math.rst
+++ b/doc/usage/extensions/math.rst
@@ -140,6 +140,12 @@ are built:
.. module:: sphinx.ext.mathjax
:synopsis: Render math using JavaScript via MathJax.
+.. warning::
+ Version 4.0 changes the version of MathJax used to version 3. You may need to
+ override ``mathjax_path`` to
+ ``https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML``
+ or update your configuration options for version 3.
+
.. versionadded:: 1.1
This extension puts math as-is into the HTML files. The JavaScript package
@@ -161,14 +167,14 @@ Sphinx but is set to automatically include it from a third-party site.
MathJax.
The default is the ``https://`` URL that loads the JS files from the
- `cdnjs`__ Content Delivery Network. See the `MathJax Getting Started
+ `jsdelivr`__ Content Delivery Network. See the `MathJax Getting Started
page`__ for details. If you want MathJax to be available offline or
without including resources from a third-party site, you have to
download it and set this value to a different path.
- __ https://cdnjs.com
+ __ https://www.jsdelivr.com/
- __ https://docs.mathjax.org/en/latest/start.html
+ __ https://www.mathjax.org/#gettingstarted
The path can be absolute or relative; if it is relative, it is relative to
the ``_static`` directory of the built docs.
diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst
index 46ef6a51ec..f0384ea9dd 100644
--- a/doc/usage/installation.rst
+++ b/doc/usage/installation.rst
@@ -12,7 +12,7 @@ Installing Sphinx
Overview
--------
-Sphinx is written in `Python`__ and supports Python 3.5+. It builds upon the
+Sphinx is written in `Python`__ and supports Python 3.6+. It builds upon the
shoulders of many third-party libraries such as `Docutils`__ and `Jinja`__,
which are installed when Sphinx is installed.
@@ -107,7 +107,30 @@ Anaconda
Windows
-------
-.. todo:: Could we start packaging this?
+Sphinx can be install using `Chocolatey`__ or
+:ref:`installed manually `.
+
+__ https://chocolatey.org/
+
+Chocolatey
+~~~~~~~~~~
+
+::
+
+ $ choco install sphinx
+
+You would need to `install Chocolatey
+`_
+before running this.
+
+For more information, refer to the `chocolatey page`__.
+
+__ https://chocolatey.org/packages/sphinx/
+
+.. _windows-other-method:
+
+Other Methods
+~~~~~~~~~~~~~
Most Windows users do not have Python installed by default, so we begin with
the installation of Python itself. To check if you already have Python
@@ -183,7 +206,7 @@ Please choose one for your purpose.
When using docker images, please use ``docker run`` command to invoke sphinx commands. For example,
you can use following command to create a Sphinx project::
- $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
+ $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
And you can following command this to build HTML document::
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index 8f596ed9a9..03b690f441 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -288,7 +288,7 @@ Roles
-----
A role or "custom interpreted text role" (:duref:`ref `) is an inline
-piece of explicit markup. It signifies that that the enclosed text should be
+piece of explicit markup. It signifies that the enclosed text should be
interpreted in a specific way. Sphinx uses this to provide semantic markup and
cross-referencing of identifiers, as described in the appropriate section. The
general syntax is ``:rolename:`content```.
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
index e8b88c21b2..995804e370 100644
--- a/doc/usage/restructuredtext/directives.rst
+++ b/doc/usage/restructuredtext/directives.rst
@@ -197,9 +197,9 @@ tables of contents. The ``toctree`` directive is the central element.
` to let a document be built, but notify Sphinx that it is not
reachable via a toctree.
- The "master document" (selected by :confval:`master_doc`) is the "root" of
- the TOC tree hierarchy. It can be used as the documentation's main page, or
- as a "full table of contents" if you don't give a ``maxdepth`` option.
+ The "root document" (selected by :confval:`root_doc`) is the "root" of the TOC
+ tree hierarchy. It can be used as the documentation's main page, or as a
+ "full table of contents" if you don't give a ``maxdepth`` option.
.. versionchanged:: 0.3
Added "globbing" option.
@@ -404,10 +404,15 @@ Showing code examples
single: sourcecode
There are multiple ways to show syntax-highlighted literal code blocks in
-Sphinx: using :ref:`reST doctest blocks `; using :ref:`reST
-literal blocks `, optionally in combination with the
-:rst:dir:`highlight` directive; using the :rst:dir:`code-block` directive; and
-using the :rst:dir:`literalinclude` directive. Doctest blocks can only be used
+Sphinx:
+
+* using :ref:`reST doctest blocks `;
+* using :ref:`reST literal blocks `, optionally in
+ combination with the :rst:dir:`highlight` directive;
+* using the :rst:dir:`code-block` directive;
+* and using the :rst:dir:`literalinclude` directive.
+
+Doctest blocks can only be used
to show interactive Python sessions, while the remaining three can be used for
other languages. Of these three, literal blocks are useful when an entire
document, or at least large sections of it, use code blocks with the same
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
index e4909f7930..bd10640558 100644
--- a/doc/usage/restructuredtext/domains.rst
+++ b/doc/usage/restructuredtext/domains.rst
@@ -202,6 +202,14 @@ The following directives are provided for module and class contents:
.. versionadded:: 2.1
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
.. rst:directive:: .. py:data:: name
Describes global data in a module, including both variables and values used
@@ -220,6 +228,14 @@ The following directives are provided for module and class contents:
.. versionadded:: 2.4
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
.. rst:directive:: .. py:exception:: name
Describes an exception class. The signature can, but need not include
@@ -259,6 +275,14 @@ The following directives are provided for module and class contents:
.. rubric:: options
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
.. rst:directive:option:: final
:type: no value
@@ -284,6 +308,14 @@ The following directives are provided for module and class contents:
.. versionadded:: 2.4
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
.. rst:directive:: .. py:method:: name(parameters)
Describes an object method. The parameters should not include the ``self``
@@ -307,6 +339,14 @@ The following directives are provided for module and class contents:
.. versionadded:: 2.1
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
.. rst:directive:option:: classmethod
:type: no value
@@ -1848,7 +1888,7 @@ currently Ada_, CoffeeScript_, Erlang_, HTTP_, Lasso_, MATLAB_, PHP_, and Ruby_
domains. Also available are domains for `Chapel`_, `Common Lisp`_, dqn_, Go_,
Jinja_, Operation_, and Scala_.
-.. _sphinx-contrib: https://bitbucket.org/birkenfeld/sphinx-contrib/
+.. _sphinx-contrib: https://github.com/sphinx-contrib
.. _Ada: https://pypi.org/project/sphinxcontrib-adadomain/
.. _Chapel: https://pypi.org/project/sphinxcontrib-chapeldomain/
diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst
index fb06e87411..fc135a0952 100644
--- a/doc/usage/theming.rst
+++ b/doc/usage/theming.rst
@@ -334,38 +334,15 @@ These themes are:
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__, GitLab__ 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.
+There are many third-party themes available for Sphinx. Some of these are for
+general use, while others are specific to an individual project.
+sphinx-themes.org__ is a gallery that showcases various themes for Sphinx,
+with demo documentation rendered under each theme. Themes can also be found
+on PyPI__ (using the classifier ``Framework :: Sphinx :: Theme``), GitHub__
+and GitLab__.
+.. __: https://sphinx-themes.org/
.. __: 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://github.com/search?utf8=%E2%9C%93&q=sphinx+theme
.. __: https://gitlab.com/explore?name=sphinx+theme
-.. __: https://sphinx-themes.org/
diff --git a/setup.cfg b/setup.cfg
index 7d629a9c56..14b071a9ec 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -45,7 +45,7 @@ paths =
line_length = 95
[mypy]
-python_version = 3.5
+python_version = 3.6
disallow_incomplete_defs = True
show_column_numbers = True
show_error_context = True
@@ -61,7 +61,6 @@ filterwarnings =
ignore::DeprecationWarning:docutils.io
ignore::DeprecationWarning:pyximport.pyximport
ignore::ImportWarning:importlib._bootstrap
- ignore::PendingDeprecationWarning:sphinx.util.pycompat
markers =
apidoc
setup_command
diff --git a/setup.py b/setup.py
index dfc80578f0..9258fded21 100644
--- a/setup.py
+++ b/setup.py
@@ -10,8 +10,8 @@
with open('README.rst') as f:
long_desc = f.read()
-if sys.version_info < (3, 5):
- print('ERROR: Sphinx requires at least Python 3.5 to run.')
+if sys.version_info < (3, 6):
+ print('ERROR: Sphinx requires at least Python 3.6 to run.')
sys.exit(1)
install_requires = [
@@ -23,7 +23,7 @@
'sphinxcontrib-qthelp',
'Jinja2>=2.3',
'Pygments>=2.0',
- 'docutils>=0.12',
+ 'docutils>=0.14',
'snowballstemmer>=1.1',
'babel>=1.3',
'alabaster>=0.7,<0.8',
@@ -200,7 +200,6 @@ def _run_domain_js(self, domain):
'Programming Language :: Python',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3 :: Only',
- 'Programming Language :: Python :: 3.5',
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.7',
'Programming Language :: Python :: 3.8',
@@ -242,7 +241,7 @@ def _run_domain_js(self, domain):
'build_sphinx = sphinx.setup_command:BuildDoc',
],
},
- python_requires=">=3.5",
+ python_requires=">=3.6",
install_requires=install_requires,
extras_require=extras_require,
cmdclass=cmdclass,
diff --git a/sphinx/__init__.py b/sphinx/__init__.py
index 7f72a3d02a..c44e7db134 100644
--- a/sphinx/__init__.py
+++ b/sphinx/__init__.py
@@ -19,11 +19,6 @@
from .deprecation import RemovedInNextVersionWarning
-if False:
- # For type annotation
- from typing import Any # NOQA
-
-
# by default, all DeprecationWarning under sphinx package will be emit.
# Users can avoid this by using environment variable: PYTHONWARNINGS=
if 'PYTHONWARNINGS' not in os.environ:
@@ -32,8 +27,8 @@
warnings.filterwarnings('ignore', "'U' mode is deprecated",
DeprecationWarning, module='docutils.io')
-__version__ = '3.5.3+'
-__released__ = '3.5.3' # used when Sphinx builds its own docs
+__version__ = '4.0.0+'
+__released__ = '4.0.0' # used when Sphinx builds its own docs
#: Version info for better programmatic use.
#:
@@ -43,7 +38,7 @@
#:
#: .. versionadded:: 1.2
#: Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (3, 5, 3, 'beta', 0)
+version_info = (4, 0, 0, 'beta', 0)
package_dir = path.abspath(path.dirname(__file__))
@@ -57,8 +52,8 @@
try:
ret = subprocess.run(['git', 'show', '-s', '--pretty=format:%h'],
cwd=package_dir,
- stdout=PIPE, stderr=PIPE)
+ stdout=PIPE, stderr=PIPE, encoding='ascii')
if ret.stdout:
- __display_version__ += '/' + ret.stdout.decode('ascii').strip()
+ __display_version__ += '/' + ret.stdout.strip()
except Exception:
pass
diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py
index 5f371e46bf..9ec4898c16 100644
--- a/sphinx/addnodes.py
+++ b/sphinx/addnodes.py
@@ -8,16 +8,12 @@
:license: BSD, see LICENSE for details.
"""
-import warnings
-from typing import Any, Dict, List, Sequence
+from typing import TYPE_CHECKING, Any, Dict, List, Sequence
from docutils import nodes
-from docutils.nodes import Element, Node
+from docutils.nodes import Element
-from sphinx.deprecation import RemovedInSphinx40Warning
-
-if False:
- # For type annotation
+if TYPE_CHECKING:
from sphinx.application import Sphinx
@@ -342,6 +338,54 @@ class pending_xref(nodes.Inline, nodes.Element):
"""
+class pending_xref_condition(nodes.Inline, nodes.TextElement):
+ """Node for cross-references that are used to choose appropriate
+ content of the reference by conditions on the resolving phase.
+
+ When the :py:class:`pending_xref` node contains one or more
+ **pending_xref_condition** nodes, the cross-reference resolver
+ should choose the content of the reference using defined conditions
+ in ``condition`` attribute of each pending_xref_condition nodes::
+
+
+
+ StringIO
+
+
+ io.StringIO
+
+ After the processing of cross-reference resolver, one of the content node
+ under pending_xref_condition node is chosen by its condition and to be
+ removed all of pending_xref_condition nodes::
+
+ # When resolved the cross-reference successfully
+
+
+ StringIO
+
+ # When resolution is failed
+
+
+ io.StringIO
+
+ .. note:: This node is only allowed to be placed under pending_xref node.
+ It is not allows to place it under other nodes. In addition,
+ pending_xref node must contain only pending_xref_condition
+ nodes if it contains one or more pending_xref_condition nodes.
+
+ The pending_xref_condition node should have **condition** attribute.
+ Domains can be store their individual conditions into the attribute to
+ filter contents on resolving phase. As a reserved condition name,
+ ``condition="*"`` is used for the fallback of resolution failure.
+ Additionally, as a recommended condition name, ``condition="resolved"``
+ is used for the representation of resolstion success in the intersphinx
+ module.
+
+ .. versionadded:: 4.0
+ """
+
+
class number_reference(nodes.reference):
"""Node for number references, similar to pending_xref."""
@@ -362,20 +406,6 @@ class literal_strong(nodes.strong, not_smartquotable):
"""
-class abbreviation(nodes.abbreviation):
- """Node for abbreviations with explanations.
-
- .. deprecated:: 2.0
- """
-
- def __init__(self, rawsource: str = '', text: str = '',
- *children: Node, **attributes: Any) -> None:
- warnings.warn("abbrevition node for Sphinx was replaced by docutils'.",
- RemovedInSphinx40Warning, stacklevel=2)
-
- super().__init__(rawsource, text, *children, **attributes)
-
-
class manpage(nodes.Inline, nodes.FixedTextElement):
"""Node for references to manpages."""
diff --git a/sphinx/application.py b/sphinx/application.py
index f61a6a5497..7812cecc96 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -14,11 +14,10 @@
import pickle
import platform
import sys
-import warnings
from collections import deque
from io import StringIO
from os import path
-from typing import IO, Any, Callable, Dict, List, Optional, Tuple, Union
+from typing import IO, TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Type, Union
from docutils import nodes
from docutils.nodes import Element, TextElement
@@ -30,14 +29,13 @@
import sphinx
from sphinx import locale, package_dir
from sphinx.config import Config
-from sphinx.deprecation import RemovedInSphinx40Warning
from sphinx.domains import Domain, Index
from sphinx.environment import BuildEnvironment
from sphinx.environment.collectors import EnvironmentCollector
from sphinx.errors import ApplicationError, ConfigError, VersionRequirementError
from sphinx.events import EventManager
from sphinx.extension import Extension
-from sphinx.highlighting import lexer_classes, lexers
+from sphinx.highlighting import lexer_classes
from sphinx.locale import __
from sphinx.project import Project
from sphinx.registry import SphinxComponentRegistry
@@ -52,10 +50,7 @@
from sphinx.util.tags import Tags
from sphinx.util.typing import RoleFunction, TitleGetter
-if False:
- # For type annotation
- from typing import Type # for python3.5.1
-
+if TYPE_CHECKING:
from docutils.nodes import Node # NOQA
from sphinx.builders import Builder
@@ -135,6 +130,9 @@ class Sphinx:
:ivar outdir: Directory for storing build documents.
"""
+ warningiserror: bool
+ _warncount: int
+
def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir: str,
buildername: str, confoverrides: Dict = None,
status: IO = sys.stdout, warning: IO = sys.stderr,
@@ -946,13 +944,6 @@ def add_post_transform(self, transform: "Type[Transform]") -> None:
"""
self.registry.add_post_transform(transform)
- def add_javascript(self, filename: str, **kwargs: Any) -> None:
- """An alias of :meth:`add_js_file`."""
- warnings.warn('The app.add_javascript() is deprecated. '
- 'Please use app.add_js_file() instead.',
- RemovedInSphinx40Warning, stacklevel=2)
- self.add_js_file(filename, **kwargs)
-
def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None:
"""Register a JavaScript file to include in the HTML output.
@@ -1032,6 +1023,8 @@ def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> Non
* - Priority
- Main purpose in Sphinx
+ * - 200
+ - default priority for built-in CSS files
* - 500
- default priority for extensions
* - 800
@@ -1061,24 +1054,6 @@ def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> Non
if hasattr(self.builder, 'add_css_file'):
self.builder.add_css_file(filename, priority=priority, **kwargs) # type: ignore
- def add_stylesheet(self, filename: str, alternate: bool = False, title: str = None
- ) -> None:
- """An alias of :meth:`add_css_file`."""
- warnings.warn('The app.add_stylesheet() is deprecated. '
- 'Please use app.add_css_file() instead.',
- RemovedInSphinx40Warning, stacklevel=2)
-
- attributes = {} # type: Dict[str, Any]
- if alternate:
- attributes['rel'] = 'alternate stylesheet'
- else:
- attributes['rel'] = 'stylesheet'
-
- if title:
- attributes['title'] = title
-
- self.add_css_file(filename, **attributes)
-
def add_latex_package(self, packagename: str, options: str = None,
after_hyperref: bool = False) -> None:
r"""Register a package to include in the LaTeX source code.
@@ -1102,7 +1077,7 @@ def add_latex_package(self, packagename: str, options: str = None,
"""
self.registry.add_latex_package(packagename, options, after_hyperref)
- def add_lexer(self, alias: str, lexer: Union[Lexer, "Type[Lexer]"]) -> None:
+ def add_lexer(self, alias: str, lexer: Type[Lexer]) -> None:
"""Register a new lexer for source code.
Use *lexer* to highlight code blocks with the given language *alias*.
@@ -1113,13 +1088,7 @@ def add_lexer(self, alias: str, lexer: Union[Lexer, "Type[Lexer]"]) -> None:
still supported until Sphinx-3.x.
"""
logger.debug('[app] adding lexer: %r', (alias, lexer))
- if isinstance(lexer, Lexer):
- warnings.warn('app.add_lexer() API changed; '
- 'Please give lexer class instead of instance',
- RemovedInSphinx40Warning, stacklevel=2)
- lexers[alias] = lexer
- else:
- lexer_classes[alias] = lexer
+ lexer_classes[alias] = lexer
def add_autodocumenter(self, cls: Any, override: bool = False) -> None:
"""Register a new documenter class for the autodoc extension.
@@ -1133,7 +1102,7 @@ def add_autodocumenter(self, cls: Any, override: bool = False) -> None:
If *override* is True, the given *cls* is forcedly installed even if
a documenter having the same name is already installed.
- .. todo:: Add real docs for Documenter and subclassing
+ See :ref:`autodoc_ext_tutorial`.
.. versionadded:: 0.6
.. versionchanged:: 2.2
diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py
index 58030bb6c8..c4ac432e42 100644
--- a/sphinx/builders/__init__.py
+++ b/sphinx/builders/__init__.py
@@ -11,7 +11,7 @@
import pickle
import time
from os import path
-from typing import Any, Dict, Iterable, List, Sequence, Set, Tuple, Union
+from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Sequence, Set, Tuple, Type, Union
from docutils import nodes
from docutils.nodes import Node
@@ -40,10 +40,7 @@
except ImportError:
multiprocessing = None
-if False:
- # For type annotation
- from typing import Type # for python3.5.1
-
+if TYPE_CHECKING:
from sphinx.application import Sphinx
@@ -416,9 +413,9 @@ def read(self) -> List[str]:
else:
self._read_serial(docnames)
- if self.config.master_doc not in self.env.all_docs:
- raise SphinxError('master file %s not found' %
- self.env.doc2path(self.config.master_doc))
+ if self.config.root_doc not in self.env.all_docs:
+ raise SphinxError('root file %s not found' %
+ self.env.doc2path(self.config.root_doc))
for retval in self.events.emit('env-updated', self.env):
if retval is not None:
@@ -520,7 +517,7 @@ def write(self, build_docnames: Iterable[str], updated_docnames: Sequence[str],
for tocdocname in self.env.files_to_rebuild.get(docname, set()):
if tocdocname in self.env.found_docs:
docnames.add(tocdocname)
- docnames.add(self.config.master_doc)
+ docnames.add(self.config.root_doc)
with progress_message(__('preparing documents')):
self.prepare_writing(docnames)
diff --git a/sphinx/builders/_epub_base.py b/sphinx/builders/_epub_base.py
index 7df3f8df57..3b19bb8d06 100644
--- a/sphinx/builders/_epub_base.py
+++ b/sphinx/builders/_epub_base.py
@@ -11,10 +11,8 @@
import html
import os
import re
-import warnings
-from collections import namedtuple
from os import path
-from typing import Any, Dict, List, Set, Tuple
+from typing import Any, Dict, List, NamedTuple, Set, Tuple
from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
from docutils import nodes
@@ -23,7 +21,6 @@
from sphinx import addnodes
from sphinx.builders.html import BuildInfo, StandaloneHTMLBuilder
-from sphinx.deprecation import RemovedInSphinx40Warning
from sphinx.locale import __
from sphinx.util import logging, status_iterator
from sphinx.util.fileutil import copy_asset_file
@@ -84,10 +81,30 @@
REFURI_RE = re.compile("([^#:]*#)(.*)")
-ManifestItem = namedtuple('ManifestItem', ['href', 'id', 'media_type'])
-Spine = namedtuple('Spine', ['idref', 'linear'])
-Guide = namedtuple('Guide', ['type', 'title', 'uri'])
-NavPoint = namedtuple('NavPoint', ['navpoint', 'playorder', 'text', 'refuri', 'children'])
+class ManifestItem(NamedTuple):
+ href: str
+ id: str
+ media_type: str
+
+
+class Spine(NamedTuple):
+ idref: str
+ linear: bool
+
+
+class Guide(NamedTuple):
+ type: str
+ title: str
+ uri: str
+
+
+class NavPoint(NamedTuple):
+ navpoint: str
+ playorder: int
+ text: str
+ refuri: str
+ children: List[Any] # mypy does not support recursive types
+ # https://github.com/python/mypy/issues/7069
def sphinx_smarty_pants(t: str, language: str = 'en') -> str:
@@ -168,18 +185,6 @@ def make_id(self, name: str) -> str:
self.id_cache[name] = id
return id
- def esc(self, name: str) -> str:
- """Replace all characters not allowed in text an attribute values."""
- warnings.warn(
- '%s.esc() is deprecated. Use html.escape() instead.' % self.__class__.__name__,
- RemovedInSphinx40Warning, stacklevel=2)
- name = name.replace('&', '&')
- name = name.replace('<', '<')
- name = name.replace('>', '>')
- name = name.replace('"', '"')
- name = name.replace('\'', ''')
- return name
-
def get_refnodes(self, doctree: Node, result: List[Dict[str, Any]]) -> List[Dict[str, Any]]: # NOQA
"""Collect section titles, their depth in the toc and the refuri."""
# XXX: is there a better way than checking the attribute
@@ -217,14 +222,14 @@ def check_refnodes(self, nodes: List[Dict[str, Any]]) -> None:
appeared.add(node['refuri'])
def get_toc(self) -> None:
- """Get the total table of contents, containing the master_doc
+ """Get the total table of contents, containing the root_doc
and pre and post files not managed by sphinx.
"""
- doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
+ doctree = self.env.get_and_resolve_doctree(self.config.root_doc,
self, prune_toctrees=False,
includehidden=True)
self.refnodes = self.get_refnodes(doctree, [])
- master_dir = path.dirname(self.config.master_doc)
+ master_dir = path.dirname(self.config.root_doc)
if master_dir:
master_dir += '/' # XXX or os.sep?
for item in self.refnodes:
@@ -232,13 +237,13 @@ def get_toc(self) -> None:
self.toc_add_files(self.refnodes)
def toc_add_files(self, refnodes: List[Dict[str, Any]]) -> None:
- """Add the master_doc, pre and post files to a list of refnodes.
+ """Add the root_doc, pre and post files to a list of refnodes.
"""
refnodes.insert(0, {
'level': 1,
- 'refuri': html.escape(self.config.master_doc + self.out_suffix),
+ 'refuri': html.escape(self.config.root_doc + self.out_suffix),
'text': ssp(html.escape(
- self.env.titles[self.config.master_doc].astext()))
+ self.env.titles[self.config.root_doc].astext()))
})
for file, text in reversed(self.config.epub_pre_files):
refnodes.insert(0, {
@@ -461,30 +466,17 @@ def handle_page(self, pagename: str, addctx: Dict, templatename: str = 'page.htm
addctx['doctype'] = self.doctype
super().handle_page(pagename, addctx, templatename, outfilename, event_arg)
- def build_mimetype(self, outdir: str = None, outname: str = 'mimetype') -> None:
+ def build_mimetype(self) -> None:
"""Write the metainfo file mimetype."""
- if outdir:
- warnings.warn('The arguments of EpubBuilder.build_mimetype() is deprecated.',
- RemovedInSphinx40Warning, stacklevel=2)
- else:
- outdir = self.outdir
+ logger.info(__('writing mimetype file...'))
+ copy_asset_file(path.join(self.template_dir, 'mimetype'), self.outdir)
- logger.info(__('writing %s file...'), outname)
- copy_asset_file(path.join(self.template_dir, 'mimetype'),
- path.join(outdir, outname))
-
- def build_container(self, outdir: str = None, outname: str = 'META-INF/container.xml') -> None: # NOQA
+ def build_container(self, outname: str = 'META-INF/container.xml') -> None: # NOQA
"""Write the metainfo file META-INF/container.xml."""
- if outdir:
- warnings.warn('The arguments of EpubBuilder.build_container() is deprecated.',
- RemovedInSphinx40Warning, stacklevel=2)
- else:
- outdir = self.outdir
-
- logger.info(__('writing %s file...'), outname)
- filename = path.join(outdir, outname)
- ensuredir(path.dirname(filename))
- copy_asset_file(path.join(self.template_dir, 'container.xml'), filename)
+ logger.info(__('writing META-INF/container.xml file...'))
+ outdir = path.join(self.outdir, 'META-INF')
+ ensuredir(outdir)
+ copy_asset_file(path.join(self.template_dir, 'container.xml'), outdir)
def content_metadata(self) -> Dict[str, Any]:
"""Create a dictionary with all metadata for the content.opf
@@ -505,23 +497,17 @@ def content_metadata(self) -> Dict[str, Any]:
metadata['guides'] = []
return metadata
- def build_content(self, outdir: str = None, outname: str = 'content.opf') -> None:
+ def build_content(self) -> None:
"""Write the metainfo file content.opf It contains bibliographic data,
a file list and the spine (the reading order).
"""
- if outdir:
- warnings.warn('The arguments of EpubBuilder.build_content() is deprecated.',
- RemovedInSphinx40Warning, stacklevel=2)
- else:
- outdir = self.outdir
-
- logger.info(__('writing %s file...'), outname)
+ logger.info(__('writing content.opf file...'))
metadata = self.content_metadata()
# files
- if not outdir.endswith(os.sep):
- outdir += os.sep
- olen = len(outdir)
+ if not self.outdir.endswith(os.sep):
+ self.outdir += os.sep
+ olen = len(self.outdir)
self.files = [] # type: List[str]
self.ignored_files = ['.buildinfo', 'mimetype', 'content.opf',
'toc.ncx', 'META-INF/container.xml',
@@ -530,7 +516,7 @@ def build_content(self, outdir: str = None, outname: str = 'content.opf') -> Non
self.config.epub_exclude_files
if not self.use_index:
self.ignored_files.append('genindex' + self.out_suffix)
- for root, dirs, files in os.walk(outdir):
+ for root, dirs, files in os.walk(self.outdir):
dirs.sort()
for fn in sorted(files):
filename = path.join(root, fn)[olen:]
@@ -620,9 +606,7 @@ def build_content(self, outdir: str = None, outname: str = 'content.opf') -> Non
html.escape(self.refnodes[0]['refuri'])))
# write the project file
- copy_asset_file(path.join(self.template_dir, 'content.opf_t'),
- path.join(outdir, outname),
- metadata)
+ copy_asset_file(path.join(self.template_dir, 'content.opf_t'), self.outdir, metadata)
def new_navpoint(self, node: Dict[str, Any], level: int, incr: bool = True) -> NavPoint:
"""Create a new entry in the toc from the node at given level."""
@@ -640,7 +624,7 @@ def build_navpoints(self, nodes: List[Dict[str, Any]]) -> List[NavPoint]:
the parent node is reinserted in the subnav.
"""
navstack = [] # type: List[NavPoint]
- navstack.append(NavPoint('dummy', '', '', '', []))
+ navstack.append(NavPoint('dummy', 0, '', '', []))
level = 0
lastnode = None
for node in nodes:
@@ -688,18 +672,12 @@ def toc_metadata(self, level: int, navpoints: List[NavPoint]) -> Dict[str, Any]:
metadata['navpoints'] = navpoints
return metadata
- def build_toc(self, outdir: str = None, outname: str = 'toc.ncx') -> None:
+ def build_toc(self) -> None:
"""Write the metainfo file toc.ncx."""
- if outdir:
- warnings.warn('The arguments of EpubBuilder.build_toc() is deprecated.',
- RemovedInSphinx40Warning, stacklevel=2)
- else:
- outdir = self.outdir
-
- logger.info(__('writing %s file...'), outname)
+ logger.info(__('writing toc.ncx file...'))
if self.config.epub_tocscope == 'default':
- doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
+ doctree = self.env.get_and_resolve_doctree(self.config.root_doc,
self, prune_toctrees=False,
includehidden=False)
refnodes = self.get_refnodes(doctree, [])
@@ -711,28 +689,21 @@ def build_toc(self, outdir: str = None, outname: str = 'toc.ncx') -> None:
navpoints = self.build_navpoints(refnodes)
level = max(item['level'] for item in self.refnodes)
level = min(level, self.config.epub_tocdepth)
- copy_asset_file(path.join(self.template_dir, 'toc.ncx_t'),
- path.join(outdir, outname),
+ copy_asset_file(path.join(self.template_dir, 'toc.ncx_t'), self.outdir,
self.toc_metadata(level, navpoints))
- def build_epub(self, outdir: str = None, outname: str = None) -> None:
+ def build_epub(self) -> None:
"""Write the epub file.
It is a zip file with the mimetype file stored uncompressed as the first
entry.
"""
- if outdir:
- warnings.warn('The arguments of EpubBuilder.build_epub() is deprecated.',
- RemovedInSphinx40Warning, stacklevel=2)
- else:
- outdir = self.outdir
- outname = self.config.epub_basename + '.epub'
-
+ outname = self.config.epub_basename + '.epub'
logger.info(__('writing %s file...'), outname)
- epub_filename = path.join(outdir, outname)
+ epub_filename = path.join(self.outdir, outname)
with ZipFile(epub_filename, 'w', ZIP_DEFLATED) as epub:
- epub.write(path.join(outdir, 'mimetype'), 'mimetype', ZIP_STORED)
+ epub.write(path.join(self.outdir, 'mimetype'), 'mimetype', ZIP_STORED)
for filename in ['META-INF/container.xml', 'content.opf', 'toc.ncx']:
- epub.write(path.join(outdir, filename), filename, ZIP_DEFLATED)
+ epub.write(path.join(self.outdir, filename), filename, ZIP_DEFLATED)
for filename in self.files:
- epub.write(path.join(outdir, filename), filename, ZIP_DEFLATED)
+ epub.write(path.join(self.outdir, filename), filename, ZIP_DEFLATED)
diff --git a/sphinx/builders/applehelp.py b/sphinx/builders/applehelp.py
deleted file mode 100644
index bfc8c8dc8a..0000000000
--- a/sphinx/builders/applehelp.py
+++ /dev/null
@@ -1,45 +0,0 @@
-"""
- sphinx.builders.applehelp
- ~~~~~~~~~~~~~~~~~~~~~~~~~
-
- Build Apple help books.
-
- :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
- :license: BSD, see LICENSE for details.
-"""
-
-import warnings
-from typing import Any, Dict
-
-from sphinxcontrib.applehelp import (AppleHelpBuilder, AppleHelpCodeSigningFailed,
- AppleHelpIndexerFailed)
-
-from sphinx.application import Sphinx
-from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
-
-deprecated_alias('sphinx.builders.applehelp',
- {
- 'AppleHelpCodeSigningFailed': AppleHelpCodeSigningFailed,
- 'AppleHelpIndexerFailed': AppleHelpIndexerFailed,
- 'AppleHelpBuilder': AppleHelpBuilder,
- },
- RemovedInSphinx40Warning,
- {
- 'AppleHelpCodeSigningFailed':
- 'sphinxcontrib.applehelp.AppleHelpCodeSigningFailed',
- 'AppleHelpIndexerFailed':
- 'sphinxcontrib.applehelp.AppleHelpIndexerFailed',
- 'AppleHelpBuilder': 'sphinxcontrib.applehelp.AppleHelpBuilder',
- })
-
-
-def setup(app: Sphinx) -> Dict[str, Any]:
- warnings.warn('sphinx.builders.applehelp has been moved to sphinxcontrib-applehelp.',
- RemovedInSphinx40Warning, stacklevel=2)
- app.setup_extension('sphinxcontrib.applehelp')
-
- return {
- 'version': 'builtin',
- 'parallel_read_safe': True,
- 'parallel_write_safe': True,
- }
diff --git a/sphinx/builders/devhelp.py b/sphinx/builders/devhelp.py
deleted file mode 100644
index 9625b62f47..0000000000
--- a/sphinx/builders/devhelp.py
+++ /dev/null
@@ -1,40 +0,0 @@
-"""
- sphinx.builders.devhelp
- ~~~~~~~~~~~~~~~~~~~~~~~
-
- Build HTML documentation and Devhelp_ support files.
-
- .. _Devhelp: https://wiki.gnome.org/Apps/Devhelp
-
- :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
- :license: BSD, see LICENSE for details.
-"""
-
-import warnings
-from typing import Any, Dict
-
-from sphinxcontrib.devhelp import DevhelpBuilder
-
-from sphinx.application import Sphinx
-from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
-
-deprecated_alias('sphinx.builders.devhelp',
- {
- 'DevhelpBuilder': DevhelpBuilder,
- },
- RemovedInSphinx40Warning,
- {
- 'DevhelpBuilder': 'sphinxcontrib.devhelp.DevhelpBuilder'
- })
-
-
-def setup(app: Sphinx) -> Dict[str, Any]:
- warnings.warn('sphinx.builders.devhelp has been moved to sphinxcontrib-devhelp.',
- RemovedInSphinx40Warning)
- app.setup_extension('sphinxcontrib.devhelp')
-
- return {
- 'version': 'builtin',
- 'parallel_read_safe': True,
- 'parallel_write_safe': True,
- }
diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py
index d1cf64eb3e..623ee45a45 100644
--- a/sphinx/builders/epub3.py
+++ b/sphinx/builders/epub3.py
@@ -10,16 +10,13 @@
"""
import html
-import warnings
-from collections import namedtuple
from os import path
-from typing import Any, Dict, List, Set, Tuple
+from typing import Any, Dict, List, NamedTuple, Set, Tuple
from sphinx import package_dir
from sphinx.application import Sphinx
from sphinx.builders import _epub_base
from sphinx.config import ENUM, Config
-from sphinx.deprecation import RemovedInSphinx40Warning
from sphinx.locale import __
from sphinx.util import logging, xmlname_checker
from sphinx.util.fileutil import copy_asset_file
@@ -29,7 +26,12 @@
logger = logging.getLogger(__name__)
-NavPoint = namedtuple('NavPoint', ['text', 'refuri', 'children'])
+class NavPoint(NamedTuple):
+ text: str
+ refuri: str
+ children: List[Any] # mypy does not support recursive types
+ # https://github.com/python/mypy/issues/7069
+
# writing modes
PAGE_PROGRESSION_DIRECTIONS = {
@@ -81,10 +83,6 @@ def handle_finish(self) -> None:
self.build_toc()
self.build_epub()
- def validate_config_value(self) -> None:
- warnings.warn('Epub3Builder.validate_config_value() is deprecated.',
- RemovedInSphinx40Warning, stacklevel=2)
-
def content_metadata(self) -> Dict:
"""Create a dictionary with all metadata for the content.opf
file properly escaped.
@@ -162,19 +160,13 @@ def navigation_doc_metadata(self, navlist: List[NavPoint]) -> Dict:
metadata['navlist'] = navlist
return metadata
- def build_navigation_doc(self, outdir: str = None, outname: str = 'nav.xhtml') -> None:
+ def build_navigation_doc(self) -> None:
"""Write the metainfo file nav.xhtml."""
- if outdir:
- warnings.warn('The arguments of Epub3Builder.build_navigation_doc() '
- 'is deprecated.', RemovedInSphinx40Warning, stacklevel=2)
- else:
- outdir = self.outdir
-
- logger.info(__('writing %s file...'), outname)
+ logger.info(__('writing nav.xhtml file...'))
if self.config.epub_tocscope == 'default':
doctree = self.env.get_and_resolve_doctree(
- self.config.master_doc, self,
+ self.config.root_doc, self,
prune_toctrees=False, includehidden=False)
refnodes = self.get_refnodes(doctree, [])
self.toc_add_files(refnodes)
@@ -182,13 +174,12 @@ def build_navigation_doc(self, outdir: str = None, outname: str = 'nav.xhtml') -
# 'includehidden'
refnodes = self.refnodes
navlist = self.build_navlist(refnodes)
- copy_asset_file(path.join(self.template_dir, 'nav.xhtml_t'),
- path.join(outdir, outname),
+ copy_asset_file(path.join(self.template_dir, 'nav.xhtml_t'), self.outdir,
self.navigation_doc_metadata(navlist))
# Add nav.xhtml to epub file
- if outname not in self.files:
- self.files.append(outname)
+ if 'nav.xhtml' not in self.files:
+ self.files.append('nav.xhtml')
def validate_config_values(app: Sphinx) -> None:
diff --git a/sphinx/builders/gettext.py b/sphinx/builders/gettext.py
index 75c95c0bc6..78ae06b74d 100644
--- a/sphinx/builders/gettext.py
+++ b/sphinx/builders/gettext.py
@@ -13,7 +13,7 @@
from datetime import datetime, timedelta, tzinfo
from os import getenv, path, walk
from time import time
-from typing import Any, Dict, Generator, Iterable, List, Set, Tuple, Union
+from typing import Any, DefaultDict, Dict, Generator, Iterable, List, Set, Tuple, Union
from uuid import uuid4
from docutils import nodes
@@ -33,33 +33,8 @@
from sphinx.util.tags import Tags
from sphinx.util.template import SphinxRenderer
-if False:
- # For type annotation
- from typing import DefaultDict # for python3.5.1
-
logger = logging.getLogger(__name__)
-POHEADER = r"""
-# SOME DESCRIPTIVE TITLE.
-# Copyright (C) %(copyright)s
-# This file is distributed under the same license as the %(project)s package.
-# FIRST AUTHOR , YEAR.
-#
-#, fuzzy
-msgid ""
-msgstr ""
-"Project-Id-Version: %(project)s %(version)s\n"
-"Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: %(ctime)s\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME \n"
-"Language-Team: LANGUAGE \n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=UTF-8\n"
-"Content-Transfer-Encoding: 8bit\n"
-
-"""[1:] # RemovedInSphinx40Warning
-
class Message:
"""An entry of translatable message."""
diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py
index c799b01767..115f735381 100644
--- a/sphinx/builders/html/__init__.py
+++ b/sphinx/builders/html/__init__.py
@@ -13,9 +13,9 @@
import posixpath
import re
import sys
-import warnings
+from datetime import datetime
from os import path
-from typing import IO, Any, Dict, Iterable, Iterator, List, Set, Tuple
+from typing import IO, Any, Dict, Iterable, Iterator, List, Set, Tuple, Type
from urllib.parse import quote
from docutils import nodes
@@ -29,7 +29,6 @@
from sphinx.application import Sphinx
from sphinx.builders import Builder
from sphinx.config import ENUM, Config
-from sphinx.deprecation import RemovedInSphinx40Warning
from sphinx.domains import Domain, Index, IndexEntry
from sphinx.environment.adapters.asset import ImageAdapter
from sphinx.environment.adapters.indexentries import IndexEntries
@@ -39,7 +38,7 @@
from sphinx.locale import _, __
from sphinx.search import js_index
from sphinx.theming import HTMLThemeFactory
-from sphinx.util import logging, md5, progress_message, status_iterator
+from sphinx.util import isurl, logging, md5, progress_message, status_iterator
from sphinx.util.docutils import is_html5_writer_available, new_document
from sphinx.util.fileutil import copy_asset
from sphinx.util.i18n import format_date
@@ -49,11 +48,6 @@
from sphinx.util.tags import Tags
from sphinx.writers.html import HTMLTranslator, HTMLWriter
-if False:
- # For type annotation
- from typing import Type # for python3.5.1
-
-
# HTML5 Writer is available or not
if is_html5_writer_available():
from sphinx.writers.html5 import HTML5Translator
@@ -256,6 +250,14 @@ def _get_translations_js(self) -> str:
return jsfile
return None
+ def _get_style_filename(self) -> str:
+ if self.config.html_style is not None:
+ return self.config.html_style
+ elif self.theme:
+ return self.theme.get_config('theme', 'stylesheet')
+ else:
+ return 'default.css'
+
def get_theme_config(self) -> Tuple[str, Dict]:
return self.config.html_theme, self.config.html_theme_options
@@ -291,6 +293,9 @@ def init_highlighter(self) -> None:
self.dark_highlighter = None
def init_css_files(self) -> None:
+ self.add_css_file('pygments.css', priority=200)
+ self.add_css_file(self._get_style_filename(), priority=200)
+
for filename, attrs in self.app.registry.css_files:
self.add_css_file(filename, **attrs)
@@ -305,6 +310,8 @@ def add_css_file(self, filename: str, **kwargs: Any) -> None:
self.css_files.append(Stylesheet(filename, **kwargs)) # type: ignore
def init_js_files(self) -> None:
+ self.add_js_file('documentation_options.js', id="documentation_options",
+ data_url_root='', priority=200)
self.add_js_file('jquery.js', priority=200)
self.add_js_file('underscore.js', priority=200)
self.add_js_file('doctools.js', priority=200)
@@ -358,6 +365,7 @@ def get_outdated_docs(self) -> Iterator[str]:
buildinfo = BuildInfo.load(fp)
if self.build_info != buildinfo:
+ logger.debug('[build target] did not match: build_info ')
yield from self.env.found_docs
return
except ValueError as exc:
@@ -372,6 +380,7 @@ def get_outdated_docs(self) -> Iterator[str]:
template_mtime = 0
for docname in self.env.found_docs:
if docname not in self.env.all_docs:
+ logger.debug('[build target] did not in env: %r', docname)
yield docname
continue
targetname = self.get_outfilename(docname)
@@ -383,6 +392,14 @@ def get_outdated_docs(self) -> Iterator[str]:
srcmtime = max(path.getmtime(self.env.doc2path(docname)),
template_mtime)
if srcmtime > targetmtime:
+ logger.debug(
+ '[build target] targetname %r(%s), template(%s), docname %r(%s)',
+ targetname,
+ datetime.utcfromtimestamp(targetmtime),
+ datetime.utcfromtimestamp(template_mtime),
+ docname,
+ datetime.utcfromtimestamp(path.getmtime(self.env.doc2path(docname))),
+ )
yield docname
except OSError:
# source doesn't exist anymore
@@ -470,13 +487,6 @@ def prepare_writing(self, docnames: Set[str]) -> None:
self._script_files = list(self.script_files)
self._css_files = list(self.css_files)
- if self.config.html_style is not None:
- stylename = self.config.html_style
- elif self.theme:
- stylename = self.theme.get_config('theme', 'stylesheet')
- else:
- stylename = 'default.css'
-
self.globalcontext = {
'embedded': self.embedded,
'project': self.config.project,
@@ -484,7 +494,8 @@ def prepare_writing(self, docnames: Set[str]) -> None:
'version': self.config.version,
'last_updated': self.last_updated,
'copyright': self.config.copyright,
- 'master_doc': self.config.master_doc,
+ 'master_doc': self.config.root_doc,
+ 'root_doc': self.config.root_doc,
'use_opensearch': self.config.html_use_opensearch,
'docstitle': self.config.html_title,
'shorttitle': self.config.html_short_title,
@@ -499,7 +510,7 @@ def prepare_writing(self, docnames: Set[str]) -> None:
'language': self.config.language,
'css_files': self.css_files,
'sphinx_version': __display_version__,
- 'style': stylename,
+ 'style': self._get_style_filename(),
'rellinks': rellinks,
'builder': self.name,
'parents': [],
@@ -786,12 +797,12 @@ def onerror(filename: str, error: Exception) -> None:
excluded, context=context, renderer=self.templates, onerror=onerror)
def copy_html_logo(self) -> None:
- if self.config.html_logo:
+ if self.config.html_logo and not isurl(self.config.html_logo):
copy_asset(path.join(self.confdir, self.config.html_logo),
path.join(self.outdir, '_static'))
def copy_html_favicon(self) -> None:
- if self.config.html_favicon:
+ if self.config.html_favicon and not isurl(self.config.html_favicon):
copy_asset(path.join(self.confdir, self.config.html_favicon),
path.join(self.outdir, '_static'))
@@ -889,21 +900,11 @@ def index_page(self, pagename: str, doctree: nodes.document, title: str) -> None
# only index pages with title
if self.indexer is not None and title:
filename = self.env.doc2path(pagename, base=None)
- try:
- metadata = self.env.metadata.get(pagename, {})
- if 'nosearch' in metadata:
- self.indexer.feed(pagename, filename, '', new_document(''))
- else:
- self.indexer.feed(pagename, filename, title, doctree)
- except TypeError:
- # fallback for old search-adapters
- self.indexer.feed(pagename, title, doctree) # type: ignore
- indexer_name = self.indexer.__class__.__name__
- warnings.warn(
- 'The %s.feed() method signature is deprecated. Update to '
- '%s.feed(docname, filename, title, doctree).' % (
- indexer_name, indexer_name),
- RemovedInSphinx40Warning, stacklevel=2)
+ metadata = self.env.metadata.get(pagename, {})
+ if 'nosearch' in metadata:
+ self.indexer.feed(pagename, filename, '', new_document(''))
+ else:
+ self.indexer.feed(pagename, filename, title, doctree)
def _get_local_toctree(self, docname: str, collapse: bool = True, **kwargs: Any) -> str:
if 'includehidden' not in kwargs:
@@ -1157,6 +1158,8 @@ def js_tag(js: JavaScript) -> str:
if value is not None:
if key == 'body':
body = value
+ elif key == 'data_url_root':
+ attrs.append('data-url_root="%s"' % pathto('', resource=True))
else:
attrs.append('%s="%s"' % (key, html.escape(value, True)))
if js.filename:
@@ -1169,6 +1172,26 @@ def js_tag(js: JavaScript) -> str:
context['js_tag'] = js_tag
+def setup_resource_paths(app: Sphinx, pagename: str, templatename: str,
+ context: Dict, doctree: Node) -> None:
+ """Set up relative resource paths."""
+ pathto = context.get('pathto')
+
+ # favicon_url
+ favicon = context.get('favicon')
+ if favicon and not isurl(favicon):
+ context['favicon_url'] = pathto('_static/' + favicon, resource=True)
+ else:
+ context['favicon_url'] = favicon
+
+ # logo_url
+ logo = context.get('logo')
+ if logo and not isurl(logo):
+ context['logo_url'] = pathto('_static/' + logo, resource=True)
+ else:
+ context['logo_url'] = logo
+
+
def validate_math_renderer(app: Sphinx) -> None:
if app.builder.format != 'html':
return
@@ -1209,27 +1232,47 @@ def validate_html_static_path(app: Sphinx, config: Config) -> None:
def validate_html_logo(app: Sphinx, config: Config) -> None:
"""Check html_logo setting."""
- if config.html_logo and not path.isfile(path.join(app.confdir, config.html_logo)):
+ if (config.html_logo and
+ not path.isfile(path.join(app.confdir, config.html_logo)) and
+ not isurl(config.html_logo)):
logger.warning(__('logo file %r does not exist'), config.html_logo)
config.html_logo = None # type: ignore
def validate_html_favicon(app: Sphinx, config: Config) -> None:
"""Check html_favicon setting."""
- if config.html_favicon and not path.isfile(path.join(app.confdir, config.html_favicon)):
+ if (config.html_favicon and
+ not path.isfile(path.join(app.confdir, config.html_favicon)) and
+ not isurl(config.html_favicon)):
logger.warning(__('favicon file %r does not exist'), config.html_favicon)
config.html_favicon = None # type: ignore
+class _stable_repr_object():
+
+ def __repr__(self):
+ return '
{%- for indexname, indexcls, content, collapse in domain_indices %}
diff --git a/sphinx/templates/htmlhelp/project.hhp b/sphinx/templates/htmlhelp/project.hhp
index b647b37138..17edc1f3dc 100644
--- a/sphinx/templates/htmlhelp/project.hhp
+++ b/sphinx/templates/htmlhelp/project.hhp
@@ -4,7 +4,7 @@ Binary Index=No
Compiled file={{ outname }}.chm
Contents file={{ outname }}.hhc
Default Window={{ outname }}
-Default topic={{ master_doc }}
+Default topic={{ root_doc }}
Display compile progress=No
Full text search stop list file={{ outname }}.stp
Full-text search=Yes
@@ -13,7 +13,7 @@ Language={{ "%#x"|format(lcid) }}
Title={{ title }}
[WINDOWS]
-{{ outname }}="{{ title }}","{{ outname }}.hhc","{{ outname }}.hhk","{{ master_doc }}","{{ master_doc }}",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0
+{{ outname }}="{{ title }}","{{ outname }}.hhc","{{ outname }}.hhk","{{ root_doc }}","{{ root_doc }}",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0
[FILES]
{%- for filename in files %}
diff --git a/sphinx/templates/latex/latex.tex_t b/sphinx/templates/latex/latex.tex_t
index e288dda938..679660fdd7 100644
--- a/sphinx/templates/latex/latex.tex_t
+++ b/sphinx/templates/latex/latex.tex_t
@@ -13,6 +13,9 @@
\ifdefined\pdfpxdimen
\let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=<%= pxunit %>\relax
+\ifdefined\pdfimageresolution
+ \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax
+\fi
<% if use_xindy -%>
%% turn off hyperref patch of \index as sphinx.xdy xindy module takes care of
%% suitable \hyperpage mark-up, working around hyperref-xindy incompatibility
@@ -32,6 +35,7 @@
<%= substitutefont %>
<%= textcyrillic %>
<%= fontpkg %>
+<%= fontsubstitution %>
<%= textgreek %>
<%= fncychap %>
\usepackage<%= sphinxpkgoptions %>{sphinx}
diff --git a/sphinx/templates/quickstart/Makefile_t b/sphinx/templates/quickstart/Makefile_t
index af9c56304c..14b2dc5943 100644
--- a/sphinx/templates/quickstart/Makefile_t
+++ b/sphinx/templates/quickstart/Makefile_t
@@ -46,6 +46,7 @@ help:
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
@echo " dummy to check syntax errors of document sources"
+ @echo " clean to remove everything in the build directory"
.PHONY: clean
clean:
diff --git a/sphinx/templates/quickstart/conf.py_t b/sphinx/templates/quickstart/conf.py_t
index 8a20fc4c8a..0c5285f9ec 100644
--- a/sphinx/templates/quickstart/conf.py_t
+++ b/sphinx/templates/quickstart/conf.py_t
@@ -64,9 +64,9 @@ templates_path = ['{{ dot }}templates']
source_suffix = {{ suffix | repr }}
{% endif -%}
-{% if master != 'index' -%}
-# The master toctree document.
-master_doc = {{ master | repr }}
+{% if root_doc != 'index' -%}
+# The root document.
+root_doc = {{ root_doc | repr }}
{% endif -%}
{% if language -%}
diff --git a/sphinx/templates/quickstart/make.bat_t b/sphinx/templates/quickstart/make.bat_t
index 830cf656e3..e5d93d1aed 100644
--- a/sphinx/templates/quickstart/make.bat_t
+++ b/sphinx/templates/quickstart/make.bat_t
@@ -43,6 +43,7 @@ if "%1" == "help" (
echo. doctest to run all doctests embedded in the documentation if enabled
echo. coverage to run coverage check of the documentation if enabled
echo. dummy to check syntax errors of document sources
+ echo. clean to remove everything in the build directory
goto end
)
diff --git a/sphinx/templates/quickstart/master_doc.rst_t b/sphinx/templates/quickstart/root_doc.rst_t
similarity index 100%
rename from sphinx/templates/quickstart/master_doc.rst_t
rename to sphinx/templates/quickstart/root_doc.rst_t
diff --git a/sphinx/testing/fixtures.py b/sphinx/testing/fixtures.py
index 1cf66283f0..c284208cec 100644
--- a/sphinx/testing/fixtures.py
+++ b/sphinx/testing/fixtures.py
@@ -8,7 +8,6 @@
:license: BSD, see LICENSE for details.
"""
-import os
import subprocess
import sys
from collections import namedtuple
@@ -90,7 +89,6 @@ def app_params(request: Any, test_params: Dict, shared_result: SharedResult,
args = [pargs[i] for i in sorted(pargs.keys())]
# ##### process pytest.mark.test_params
-
if test_params['shared_result']:
if 'srcdir' in kwargs:
raise pytest.Exception('You can not specify shared_result and '
@@ -236,10 +234,7 @@ def sphinx_test_tempdir(tmpdir_factory: Any) -> "util.path":
"""
temporary directory that wrapped with `path` class.
"""
- tmpdir = os.environ.get('SPHINX_TEST_TEMPDIR') # RemovedInSphinx40Warning
- if tmpdir is None:
- tmpdir = tmpdir_factory.getbasetemp()
-
+ tmpdir = tmpdir_factory.getbasetemp()
return util.path(tmpdir).abspath()
diff --git a/sphinx/testing/util.py b/sphinx/testing/util.py
index 7d0cde143a..7868f4d625 100644
--- a/sphinx/testing/util.py
+++ b/sphinx/testing/util.py
@@ -21,15 +21,12 @@
from docutils.parsers.rst import directives, roles
from sphinx import application, locale
-from sphinx.deprecation import RemovedInSphinx40Warning
from sphinx.pycode import ModuleAnalyzer
from sphinx.testing.path import path
from sphinx.util.osutil import relpath
__all__ = [
- 'Struct',
- 'SphinxTestApp', 'SphinxTestAppWrapperForSkipBuilding',
- 'remove_unicode_literals',
+ 'Struct', 'SphinxTestApp', 'SphinxTestAppWrapperForSkipBuilding',
]
@@ -177,12 +174,6 @@ def build(self, *args: Any, **kwargs: Any) -> None:
_unicode_literals_re = re.compile(r'u(".*?")|u(\'.*?\')')
-def remove_unicode_literals(s: str) -> str:
- warnings.warn('remove_unicode_literals() is deprecated.',
- RemovedInSphinx40Warning, stacklevel=2)
- return _unicode_literals_re.sub(lambda x: x.group(1) or x.group(2), s)
-
-
def find_files(root: str, suffix: bool = None) -> Generator[str, None, None]:
for dirpath, dirs, files in os.walk(root, followlinks=True):
dirpath = path(dirpath)
diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty
index e6c27c123e..a71c64ffca 100644
--- a/sphinx/texinputs/sphinx.sty
+++ b/sphinx/texinputs/sphinx.sty
@@ -6,7 +6,7 @@
%
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2021/01/23 v3.5.0 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2021/01/27 v4.0.0 LaTeX package (Sphinx markup)]
% provides \ltx@ifundefined
% (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -31,262 +31,20 @@
}}
-%% PACKAGES
-%
-% we delay handling of options to after having loaded packages, because
-% of the need to use \definecolor.
-\RequirePackage{graphicx}
-\@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}}
-% for \text macro and \iffirstchoice@ conditional even if amsmath not loaded
-\RequirePackage{amstext}
-\RequirePackage{textcomp}% "warn" option issued from template
-\RequirePackage[nobottomtitles*]{titlesec}
-\@ifpackagelater{titlesec}{2016/03/15}%
- {\@ifpackagelater{titlesec}{2016/03/21}%
- {}%
- {\newif\ifsphinx@ttlpatch@ok
- \IfFileExists{etoolbox.sty}{%
- \RequirePackage{etoolbox}%
- \patchcmd{\ttlh@hang}{\parindent\z@}{\parindent\z@\leavevmode}%
- {\sphinx@ttlpatch@oktrue}{}%
- \ifsphinx@ttlpatch@ok
- \patchcmd{\ttlh@hang}{\noindent}{}{}{\sphinx@ttlpatch@okfalse}%
- \fi
- }{}%
- \ifsphinx@ttlpatch@ok
- \typeout{^^J Package Sphinx Info: ^^J
- **** titlesec 2.10.1 successfully patched for bugfix ****^^J}%
- \else
- \AtEndDocument{\PackageWarningNoLine{sphinx}{^^J%
-******** titlesec 2.10.1 has a bug, (section numbers disappear) ......|^^J%
-******** and Sphinx could not patch it, perhaps because your local ...|^^J%
-******** copy is already fixed without a changed release date. .......|^^J%
-******** If not, you must update titlesec! ...........................|}}%
- \fi
- }%
- }{}
-\RequirePackage{tabulary}
-% tabulary has a bug with its re-definition of \multicolumn in its first pass
-% which is not \long. But now Sphinx does not use LaTeX's \multicolumn but its
-% own macro. Hence we don't even need to patch tabulary. See sphinxmulticell.sty
-% X or S (Sphinx) may have meanings if some table package is loaded hence
-% \X was chosen to avoid possibility of conflict
-\newcolumntype{\X}[2]{p{\dimexpr
- (\linewidth-\arrayrulewidth)*#1/#2-\tw@\tabcolsep-\arrayrulewidth\relax}}
-\newcolumntype{\Y}[1]{p{\dimexpr
- #1\dimexpr\linewidth-\arrayrulewidth\relax-\tw@\tabcolsep-\arrayrulewidth\relax}}
-% using here T (for Tabulary) feels less of a problem than the X could be
-\newcolumntype{T}{J}%
-% For tables allowing pagebreaks
-\RequirePackage{longtable}
-% User interface to set-up whitespace before and after tables:
-\newcommand*\sphinxtablepre {0pt}%
-\newcommand*\sphinxtablepost{\medskipamount}%
-% Space from caption baseline to top of table or frame of literal-block
-\newcommand*\sphinxbelowcaptionspace{.5\sphinxbaselineskip}%
-% as one can not use \baselineskip from inside longtable (it is zero there)
-% we need \sphinxbaselineskip, which defaults to \baselineskip
-\def\sphinxbaselineskip{\baselineskip}%
-% The following is to ensure that, whether tabular(y) or longtable:
-% - if a caption is on top of table:
-% a) the space between its last baseline and the top rule of table is
-% exactly \sphinxbelowcaptionspace
-% b) the space from last baseline of previous text to first baseline of
-% caption is exactly \parskip+\baselineskip+ height of a strut.
-% c) the caption text will wrap at width \LTcapwidth (4in)
-% - make sure this works also if "caption" package is loaded by user
-% (with its width or margin option taking place of \LTcapwidth role)
-% TODO: obtain same for caption of literal block: a) & c) DONE, b) TO BE DONE
+%% OPTION HANDLING
%
-% To modify space below such top caption, adjust \sphinxbelowcaptionspace
-% To add or remove space above such top caption, adjust \sphinxtablepre:
-% notice that \abovecaptionskip, \belowcaptionskip, \LTpre are **ignored**
-% A. Table with longtable
-\def\sphinxatlongtablestart
- {\par
- \vskip\parskip
- \vskip\dimexpr\sphinxtablepre\relax % adjust vertical position
- \vbox{}% get correct baseline from above
- \LTpre\z@skip\LTpost\z@skip % set to zero longtable's own skips
- \edef\sphinxbaselineskip{\dimexpr\the\dimexpr\baselineskip\relax\relax}%
- }%
-% Compatibility with caption package
-\def\sphinxthelongtablecaptionisattop{%
- \spx@ifcaptionpackage{\noalign{\vskip-\belowcaptionskip}}{}%
-}%
-% Achieves exactly \sphinxbelowcaptionspace below longtable caption
-\def\sphinxlongtablecapskipadjust
- {\dimexpr-\dp\strutbox
- -\spx@ifcaptionpackage{\abovecaptionskip}{\sphinxbaselineskip}%
- +\sphinxbelowcaptionspace\relax}%
-\def\sphinxatlongtableend{\@nobreakfalse % latex3/latex2e#173
- \prevdepth\z@\vskip\sphinxtablepost\relax}%
-% B. Table with tabular or tabulary
-\def\sphinxattablestart{\par\vskip\dimexpr\sphinxtablepre\relax}%
-\let\sphinxattableend\sphinxatlongtableend
-% This is used by tabular and tabulary templates
-\newcommand*\sphinxcapstartof[1]{%
- \vskip\parskip
- \vbox{}% force baselineskip for good positioning by capstart of hyperanchor
- % hyperref puts the anchor 6pt above this baseline; in case of caption
- % this baseline will be \ht\strutbox above first baseline of caption
- \def\@captype{#1}%
- \capstart
-% move back vertically, as tabular (or its caption) will compensate
- \vskip-\baselineskip\vskip-\parskip
-}%
-\def\sphinxthecaptionisattop{% locate it after \sphinxcapstartof
- \spx@ifcaptionpackage
- {\caption@setposition{t}%
- \vskip\baselineskip\vskip\parskip % undo those from \sphinxcapstartof
- \vskip-\belowcaptionskip % anticipate caption package skip
- % caption package uses a \vbox, not a \vtop, so "single line" case
- % gives different result from "multi-line" without this:
- \nointerlineskip
- }%
- {}%
-}%
-\def\sphinxthecaptionisatbottom{% (not finalized; for template usage)
- \spx@ifcaptionpackage{\caption@setposition{b}}{}%
-}%
-% The aim of \sphinxcaption is to apply to tabular(y) the maximal width
-% of caption as done by longtable
-\def\sphinxtablecapwidth{\LTcapwidth}%
-\newcommand\sphinxcaption{\@dblarg\spx@caption}%
-\long\def\spx@caption[#1]#2{%
- \noindent\hb@xt@\linewidth{\hss
- \vtop{\@tempdima\dimexpr\sphinxtablecapwidth\relax
-% don't exceed linewidth for the caption width
- \ifdim\@tempdima>\linewidth\hsize\linewidth\else\hsize\@tempdima\fi
-% longtable ignores \abovecaptionskip/\belowcaptionskip, so do the same here
- \abovecaptionskip\sphinxabovecaptionskip % \z@skip
- \belowcaptionskip\sphinxbelowcaptionskip % \z@skip
- \caption[{#1}]%
- {\strut\ignorespaces#2\ifhmode\unskip\@finalstrut\strutbox\fi}%
- }\hss}%
- \par\prevdepth\dp\strutbox
-}%
-\def\sphinxabovecaptionskip{\z@skip}% Do not use! Flagged for removal
-\def\sphinxbelowcaptionskip{\z@skip}% Do not use! Flagged for removal
-% This wrapper of \abovecaptionskip is used in sphinxVerbatim for top
-% caption, and with another value in sphinxVerbatimintable
-% TODO: To unify space above caption of a code-block with the one above
-% caption of a table/longtable, \abovecaptionskip must not be used
-% This auxiliary will get renamed and receive a different meaning
-% in future.
-\def\spx@abovecaptionskip{\abovecaptionskip}%
-% Achieve \sphinxbelowcaptionspace below a caption located above a tabular
-% or a tabulary
-\newcommand\sphinxaftertopcaption
-{%
- \spx@ifcaptionpackage
- {\par\prevdepth\dp\strutbox\nobreak\vskip-\abovecaptionskip}{\nobreak}%
- \vskip\dimexpr\sphinxbelowcaptionspace\relax
- \vskip-\baselineskip\vskip-\parskip
-}%
-% varwidth is crucial for our handling of general contents in merged cells
-\RequirePackage{varwidth}
-% but addition of a compatibility patch with hyperref is needed
-% (tested with varwidth v 0.92 Mar 2009)
-\AtBeginDocument {%
- \let\@@vwid@Hy@raisedlink\Hy@raisedlink
- \long\def\@vwid@Hy@raisedlink#1{\@vwid@wrap{\@@vwid@Hy@raisedlink{#1}}}%
- \edef\@vwid@setup{%
- \let\noexpand\Hy@raisedlink\noexpand\@vwid@Hy@raisedlink % HYPERREF !
- \unexpanded\expandafter{\@vwid@setup}}%
-}%
-% Homemade package to handle merged cells
-\RequirePackage{sphinxmulticell}
-\RequirePackage{makeidx}
-% For framing code-blocks and warning type notices, and shadowing topics
-\RequirePackage{framed}
+
+% We first handle options then load packages, but we need \definecolor from
+% xcolor/color.
+
+% FIXME: we should \RequirePackage{xcolor} always now
% The xcolor package draws better fcolorboxes around verbatim code
\IfFileExists{xcolor.sty}{
\RequirePackage{xcolor}
}{
\RequirePackage{color}
}
-% For highlighted code.
-\RequirePackage{fancyvrb}
-\define@key{FV}{hllines}{\def\sphinx@verbatim@checkifhl##1{\in@{, ##1,}{#1}}}
-% sphinxVerbatim must be usable by third party without requiring hllines set-up
-\def\sphinxresetverbatimhllines{\def\sphinx@verbatim@checkifhl##1{\in@false}}
-\sphinxresetverbatimhllines
-% For hyperlinked footnotes in tables; also for gathering footnotes from
-% topic and warning blocks. Also to allow code-blocks in footnotes.
-\RequirePackage{footnotehyper-sphinx}
-% For the H specifier. Do not \restylefloat{figure}, it breaks Sphinx code
-% for allowing figures in tables.
-\RequirePackage{float}
-% For floating figures in the text. Better to load after float.
-\RequirePackage{wrapfig}
-% Separate paragraphs by space by default.
-\IfFileExists{parskip-2001-04-09.sty}% since September 2018 TeXLive update
-% new parskip.sty, but let it rollback to old one.
-% hopefully TeX installation not broken and LaTeX kernel not too old
- {\RequirePackage{parskip}[=v1]}
-% standard one from 1989. Admittedly \section of article/book gives possibly
-% anomalous spacing, but we can't require September 2018 release for some time.
- {\RequirePackage{parskip}}
-% For parsed-literal blocks.
-\RequirePackage{alltt}
-% Display "real" single quotes in literal blocks.
-\RequirePackage{upquote}
-% control caption around literal-block
-\RequirePackage{capt-of}
-\RequirePackage{needspace}
-% LaTeX 2018-04-01 and later provides \@removefromreset
-\ltx@ifundefined{@removefromreset}
- {\RequirePackage{remreset}}
- {}% avoid warning
-% To support hlist directive
-\RequirePackage{multicol}
-% to make pdf with correct encoded bookmarks in Japanese
-% this should precede the hyperref package
-\ifx\kanjiskip\@undefined
-% for non-Japanese: make sure bookmarks are ok also with lualatex
- \PassOptionsToPackage{pdfencoding=unicode}{hyperref}
-\else
- \RequirePackage{atbegshi}
- \ifx\ucs\@undefined
- \ifnum 42146=\euc"A4A2
- \AtBeginShipoutFirst{\special{pdf:tounicode EUC-UCS2}}
- \else
- \AtBeginShipoutFirst{\special{pdf:tounicode 90ms-RKSJ-UCS2}}
- \fi
- \else
- \AtBeginShipoutFirst{\special{pdf:tounicode UTF8-UCS2}}
- \fi
-\fi
-\ifx\@jsc@uplatextrue\@undefined\else
- \PassOptionsToPackage{setpagesize=false}{hyperref}
-\fi
-
-% These options can be overriden inside 'hyperref' key
-% or by later use of \hypersetup.
-\PassOptionsToPackage{colorlinks,breaklinks,%
- linkcolor=InnerLinkColor,filecolor=OuterLinkColor,%
- menucolor=OuterLinkColor,urlcolor=OuterLinkColor,%
- citecolor=InnerLinkColor}{hyperref}
-
-% stylesheet for highlighting with pygments
-\RequirePackage{sphinxhighlight}
-% fix baseline increase from Pygments latex formatter in case of error tokens
-% and keep \fboxsep's scope local via added braces
-\def\PYG@tok@err{%
- \def\PYG@bc##1{{\setlength{\fboxsep}{-\fboxrule}%
- \fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}%
-}
-\def\PYG@tok@cs{%
- \def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}%
- \def\PYG@bc##1{{\setlength{\fboxsep}{0pt}%
- \colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}%
-}%
-
-
-%% OPTIONS
-%
% Handle options via "kvoptions" (later loaded by hyperref anyhow)
\RequirePackage{kvoptions}
\SetupKeyvalOptions{prefix=spx@opt@} % use \spx@opt@ prefix
@@ -415,6 +173,7 @@
\DisableKeyvalOption{sphinx}{numfigreset}
\DisableKeyvalOption{sphinx}{nonumfigreset}
\DisableKeyvalOption{sphinx}{mathnumfig}
+% FIXME: this is unrelated to an option, move this elsewhere
% To allow hyphenation of first word in narrow contexts; no option,
% customization to be done via 'preamble' key
\newcommand*\sphinxAtStartPar{\leavevmode\nobreak\hskip\z@skip}
@@ -424,426 +183,121 @@
\newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}}
-%% ALPHANUMERIC LIST ITEMS
-\newcommand\sphinxsetlistlabels[5]
-{% #1 = style, #2 = enum, #3 = enumnext, #4 = prefix, #5 = suffix
- % #2 and #3 are counters used by enumerate environement e.g. enumi, enumii.
- % #1 is a macro such as \arabic or \alph
- % prefix and suffix are strings (by default empty and a dot).
- \@namedef{the#2}{#1{#2}}%
- \@namedef{label#2}{#4\@nameuse{the#2}#5}%
- \@namedef{p@#3}{\@nameuse{p@#2}#4\@nameuse{the#2}#5}%
-}%
-
-
-%% MAXLISTDEPTH
+%% MISCELLANEOUS CONTEXT
%
-% remove LaTeX's cap on nesting depth if 'maxlistdepth' key used.
-% This is a hack, which works with the standard classes: it assumes \@toodeep
-% is always used in "true" branches: "\if ... \@toodeep \else .. \fi."
-
-% will force use the "false" branch (if there is one)
-\def\spx@toodeep@hack{\fi\iffalse}
-
-% do nothing if 'maxlistdepth' key not used or if package enumitem loaded.
-\ifnum\spx@opt@maxlistdepth=\z@\expandafter\@gobbletwo\fi
+% flag to be set in a framed environment
+% (defined here as currently needed by three sphinxlatex....sty files and
+% even if not needed if such files are replaced, the definition does no harm)
+\newif\ifspx@inframed
+%
+% \spx@ifcaptionpackage (defined at begin document)
+% is needed currently in macros from:
+% sphinxlatexliterals.sty (sphinxVerbatim)
+% sphinxlatextables.sty (for some macros used in the table templates)
+%
+% \sphinxcaption is mark-up injected by the tabular and tabulary templates
+% it is defined in sphinxlatextables.sty
+%
+% store the original \caption macro for usage with figures inside longtable
+% and tabulary cells. Make sure we get the final \caption in presence of
+% caption package, whether the latter was loaded before or after sphinx.
\AtBeginDocument{%
-\@ifpackageloaded{enumitem}{\remove@to@nnil}{}%
- \let\spx@toodeepORI\@toodeep
- \def\@toodeep{%
- \ifnum\@listdepth<\spx@opt@maxlistdepth\relax
- \expandafter\spx@toodeep@hack
- \else
- \expandafter\spx@toodeepORI
- \fi}%
-% define all missing \@list... macros
- \count@\@ne
- \loop
- \ltx@ifundefined{@list\romannumeral\the\count@}
- {\iffalse}{\iftrue\advance\count@\@ne}%
- \repeat
- \loop
- \ifnum\count@>\spx@opt@maxlistdepth\relax\else
- \expandafter\let
- \csname @list\romannumeral\the\count@\expandafter\endcsname
- \csname @list\romannumeral\the\numexpr\count@-\@ne\endcsname
- % workaround 2.6--3.2d babel-french issue (fixed in 3.2e; no change needed)
- \ltx@ifundefined{leftmargin\romannumeral\the\count@}
- {\expandafter\let
- \csname leftmargin\romannumeral\the\count@\expandafter\endcsname
- \csname leftmargin\romannumeral\the\numexpr\count@-\@ne\endcsname}{}%
- \advance\count@\@ne
- \repeat
-% define all missing enum... counters and \labelenum... macros and \p@enum..
- \count@\@ne
- \loop
- \ltx@ifundefined{c@enum\romannumeral\the\count@}
- {\iffalse}{\iftrue\advance\count@\@ne}%
- \repeat
- \loop
- \ifnum\count@>\spx@opt@maxlistdepth\relax\else
- \newcounter{enum\romannumeral\the\count@}%
- \expandafter\def
- \csname labelenum\romannumeral\the\count@\expandafter\endcsname
- \expandafter
- {\csname theenum\romannumeral\the\numexpr\count@\endcsname.}%
- \expandafter\def
- \csname p@enum\romannumeral\the\count@\expandafter\endcsname
- \expandafter
- {\csname p@enum\romannumeral\the\numexpr\count@-\@ne\expandafter
- \endcsname\csname theenum\romannumeral\the\numexpr\count@-\@ne\endcsname.}%
- \advance\count@\@ne
- \repeat
-% define all missing labelitem... macros
- \count@\@ne
- \loop
- \ltx@ifundefined{labelitem\romannumeral\the\count@}
- {\iffalse}{\iftrue\advance\count@\@ne}%
- \repeat
- \loop
- \ifnum\count@>\spx@opt@maxlistdepth\relax\else
- \expandafter\let
- \csname labelitem\romannumeral\the\count@\expandafter\endcsname
- \csname labelitem\romannumeral\the\numexpr\count@-\@ne\endcsname
- \advance\count@\@ne
- \repeat
- \PackageInfo{sphinx}{maximal list depth extended to \spx@opt@maxlistdepth}%
-\@gobble\@nnil
+ \let\spx@originalcaption\caption
+ \@ifpackageloaded{caption}
+ {\let\spx@ifcaptionpackage\@firstoftwo
+ \caption@AtBeginDocument*{\let\spx@originalcaption\caption}%
+% in presence of caption package, drop our own \sphinxcaption whose aim was to
+% ensure same width of caption to all kinds of tables (tabular(y), longtable),
+% because caption package has its own width (or margin) option
+ \def\sphinxcaption{\caption}%
+ }%
+ {\let\spx@ifcaptionpackage\@secondoftwo}%
}
-
-%% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS
+%% PASS OPTIONS
%
-% fix the double index and bibliography on the table of contents
-% in jsclasses (Japanese standard document classes)
-\ifx\@jsc@uplatextrue\@undefined\else
- \renewenvironment{sphinxtheindex}
- {\cleardoublepage\phantomsection
- \begin{theindex}}
- {\end{theindex}}
-
- \renewenvironment{sphinxthebibliography}[1]
- {\cleardoublepage% \phantomsection % not needed here since TeXLive 2010's hyperref
- \begin{thebibliography}{#1}}
- {\end{thebibliography}}
-\fi
-
-% disable \@chappos in Appendix in pTeX
-\ifx\kanjiskip\@undefined\else
- \let\py@OldAppendix=\appendix
- \renewcommand{\appendix}{
- \py@OldAppendix
- \gdef\@chappos{}
- }
-\fi
+% pass options to hyperref; it must not have been loaded already
+\input{sphinxoptionshyperref.sty}
+% pass options to geometry; it must not have been loaded already
+\input{sphinxoptionsgeometry.sty}
-% make commands known to non-Sphinx document classes
-\providecommand*{\sphinxmaketitle}{\maketitle}
-\providecommand*{\sphinxtableofcontents}{\tableofcontents}
-\ltx@ifundefined{sphinxthebibliography}
- {\newenvironment
- {sphinxthebibliography}{\begin{thebibliography}}{\end{thebibliography}}%
- }
- {}% else clause of \ltx@ifundefined
-\ltx@ifundefined{sphinxtheindex}
- {\newenvironment{sphinxtheindex}{\begin{theindex}}{\end{theindex}}}%
- {}% else clause of \ltx@ifundefined
-
-% for usage with xindy: this string gets internationalized in preamble
-\newcommand*{\sphinxnonalphabeticalgroupname}{}
-% redefined in preamble, headings for makeindex produced index
-\newcommand*{\sphinxsymbolsname}{}
-\newcommand*{\sphinxnumbersname}{}
%% COLOR (general)
%
-% FIXME: \normalcolor should probably be used in place of \py@NormalColor
-% elsewhere, and \py@NormalColor should never be defined. \normalcolor
-% switches to the colour from last \color call in preamble.
+% FIXME: these two should be deprecated
+%
+% FIXME: \normalcolor should be used and \py@NormalColor never defined
\def\py@NormalColor{\color{black}}
-% FIXME: it is probably better to use \color{TitleColor}, as TitleColor
-% can be customized from 'sphinxsetup', and drop usage of \py@TitleColor
+% FIXME: \color{TitleColor} should be used directly and \py@TitleColor
+% should never get defined.
\def\py@TitleColor{\color{TitleColor}}
-% FIXME: this line should be dropped, as "9" is default anyhow.
-\ifdefined\pdfcompresslevel\pdfcompresslevel = 9 \fi
-%% PAGE STYLING
+%% PACKAGES
%
-% Style parameters and macros used by most documents here
-\raggedbottom
-\sloppy
-\hbadness = 5000 % don't print trivial gripes
-
-% Use \pagestyle{normal} as the primary pagestyle for text.
-% Redefine the 'normal' header/footer style when using "fancyhdr" package:
-\@ifpackageloaded{fancyhdr}{%
- \ltx@ifundefined{c@chapter}
- {% no \chapter, "howto" (non-Japanese) docclass
- \fancypagestyle{plain}{
- \fancyhf{}
- \fancyfoot[C]{{\py@HeaderFamily\thepage}}
- \renewcommand{\headrulewidth}{0pt}
- \renewcommand{\footrulewidth}{0pt}
- }
- % Same as 'plain', this way we can use it in template
- % FIXME: shouldn't this have a running header with Name and Release like 'manual'?
- \fancypagestyle{normal}{
- \fancyhf{}
- \fancyfoot[C]{{\py@HeaderFamily\thepage}}
- \renewcommand{\headrulewidth}{0pt}
- \renewcommand{\footrulewidth}{0pt}
- }
- }%
- {% classes with \chapter command
- \fancypagestyle{normal}{
- \fancyhf{}
- \fancyfoot[RO]{{\py@HeaderFamily\thepage}}
- \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
- \fancyhead[RO]{{\py@HeaderFamily \@title\sphinxheadercomma\py@release}}
- \if@twoside
- \fancyfoot[LE]{{\py@HeaderFamily\thepage}}
- \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
- \fancyhead[LE]{{\py@HeaderFamily \@title\sphinxheadercomma\py@release}}
- \fi
- \renewcommand{\headrulewidth}{0.4pt}
- \renewcommand{\footrulewidth}{0.4pt}
- % define chaptermark with \@chappos when \@chappos is available for Japanese
- \ltx@ifundefined{@chappos}{}
- {\def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}}}
- }
- % Update the plain style so we get the page number & footer line,
- % but not a chapter or section title. This is to keep the first
- % page of a chapter `clean.'
- \fancypagestyle{plain}{
- \fancyhf{}
- \fancyfoot[RO]{{\py@HeaderFamily\thepage}}
- \if@twoside\fancyfoot[LE]{{\py@HeaderFamily\thepage}}\fi
- \renewcommand{\headrulewidth}{0pt}
- \renewcommand{\footrulewidth}{0.4pt}
- }
- }
- }
- {% no fancyhdr: memoir class
- % Provide default for 'normal' style simply as an alias of 'plain' style
- % This way we can use \pagestyle{normal} in LaTeX template
- \def\ps@normal{\ps@plain}
- % Users of memoir class are invited to redefine 'normal' style in preamble
- }
+% as will be indicated below, secondary style files load some more packages
+%
+% For \text macro (sphinx.util.texescape)
+% also for usage of \firstchoice@true(false) in sphinxlatexgraphics.sty
+\RequirePackage{amstext}
+% It was passed "warn" option from latex template in case it is already loaded
+% via some other package before \usepackage{sphinx} in preamble
+\RequirePackage{textcomp}
+% For the H specifier. Do not \restylefloat{figure}, it breaks Sphinx code
+% for allowing figures in tables.
+\RequirePackage{float}
+% For floating figures in the text. Better to load after float.
+\RequirePackage{wrapfig}
+% Provides \captionof, used once by latex writer (\captionof{figure})
+\RequirePackage{capt-of}
+% Support hlist directive
+\RequirePackage{multicol}
-% geometry
-\ifx\kanjiskip\@undefined
- \PassOptionsToPackage{%
- hmargin={\unexpanded{\spx@opt@hmargin}},%
- vmargin={\unexpanded{\spx@opt@vmargin}},%
- marginpar=\unexpanded{\spx@opt@marginpar}}
- {geometry}
-\else
- % set text width for Japanese documents to be integer multiple of 1zw
- % and text height to be integer multiple of \baselineskip
- % the execution is delayed to \sphinxsetup then geometry.sty
- \normalsize\normalfont
- \newcommand*\sphinxtextwidthja[1]{%
- \if@twocolumn\tw@\fi
- \dimexpr
- \numexpr\dimexpr\paperwidth-\tw@\dimexpr#1\relax\relax/
- \dimexpr\if@twocolumn\tw@\else\@ne\fi zw\relax
- zw\relax}%
- \newcommand*\sphinxmarginparwidthja[1]{%
- \dimexpr\numexpr\dimexpr#1\relax/\dimexpr1zw\relax zw\relax}%
- \newcommand*\sphinxtextlinesja[1]{%
- \numexpr\@ne+\dimexpr\paperheight-\topskip-\tw@\dimexpr#1\relax\relax/
- \baselineskip\relax}%
- \ifx\@jsc@uplatextrue\@undefined\else
- % the way we found in order for the papersize special written by
- % geometry in the dvi file to be correct in case of jsbook class
- \ifnum\mag=\@m\else % do nothing special if nomag class option or 10pt
- \PassOptionsToPackage{truedimen}{geometry}%
- \fi
- \fi
- \PassOptionsToPackage{%
- hmarginratio={1:1},%
- textwidth=\unexpanded{\sphinxtextwidthja{\spx@opt@hmargin}},%
- vmarginratio={1:1},%
- lines=\unexpanded{\sphinxtextlinesja{\spx@opt@vmargin}},%
- marginpar=\unexpanded{\sphinxmarginparwidthja{\spx@opt@marginpar}},%
- footskip=2\baselineskip,%
- }{geometry}%
- \AtBeginDocument
- {% update a dimension used by the jsclasses
- \ifx\@jsc@uplatextrue\@undefined\else\fullwidth\textwidth\fi
- % for some reason, jreport normalizes all dimensions with \@settopoint
- \@ifclassloaded{jreport}
- {\@settopoint\textwidth\@settopoint\textheight\@settopoint\marginparwidth}
- {}% <-- "false" clause of \@ifclassloaded
- }%
-\fi
-% fix fncychap's bug which uses prematurely the \textwidth value
-\@ifpackagewith{fncychap}{Bjornstrup}
- {\AtBeginDocument{\mylen\textwidth\advance\mylen-2\myhi}}%
- {}% <-- "false" clause of \@ifpackagewith
+%% GRAPHICS
+%
+% It will always be needed, so let's load it here
+\RequirePackage{graphicx}
+\input{sphinxlatexgraphics.sty}
-%% TITLES
+%% FRAMED ENVIRONMENTS
%
-% Since Sphinx 1.5, users should use HeaderFamily key to 'sphinxsetup' rather
-% than defining their own \py@HeaderFamily command (which is still possible).
-% Memo: \py@HeaderFamily is also used by \maketitle as defined in
-% sphinxmanual.cls/sphinxhowto.cls
-\newcommand{\py@HeaderFamily}{\spx@opt@HeaderFamily}
+\input{sphinxlatexadmonitions.sty}
+\input{sphinxlatexliterals.sty}
+\input{sphinxlatexshadowbox.sty}
-% This sets up the fancy chapter headings that make the documents look
-% at least a little better than the usual LaTeX output.
-\@ifpackagewith{fncychap}{Bjarne}{
- \ChNameVar {\raggedleft\normalsize \py@HeaderFamily}
- \ChNumVar {\raggedleft\Large \py@HeaderFamily}
- \ChTitleVar{\raggedleft\Large \py@HeaderFamily}
- % This creates (numbered) chapter heads without the leading \vspace*{}:
- \def\@makechapterhead#1{%
- {\parindent \z@ \raggedright \normalfont
- \ifnum \c@secnumdepth >\m@ne
- \if@mainmatter
- \DOCH
- \fi
- \fi
- \interlinepenalty\@M
- \if@mainmatter
- \DOTI{#1}%
- \else%
- \DOTIS{#1}%
- \fi
- }}
-}{}% <-- "false" clause of \@ifpackagewith
-% Augment the sectioning commands used to get our own font family in place,
-% and reset some internal data items (\titleformat from titlesec package)
-\titleformat{\section}{\Large\py@HeaderFamily}%
- {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}
-\titleformat{\subsection}{\large\py@HeaderFamily}%
- {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}
-\titleformat{\subsubsection}{\py@HeaderFamily}%
- {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}
-% By default paragraphs (and subsubsections) will not be numbered because
-% sphinxmanual.cls and sphinxhowto.cls set secnumdepth to 2
-\titleformat{\paragraph}{\py@HeaderFamily}%
- {\py@TitleColor\theparagraph}{0.5em}{\py@TitleColor}
-\titleformat{\subparagraph}{\py@HeaderFamily}%
- {\py@TitleColor\thesubparagraph}{0.5em}{\py@TitleColor}
+%% PYGMENTS
+% stylesheet for highlighting with pygments
+\RequirePackage{sphinxhighlight}
+% fix baseline increase from Pygments latex formatter in case of error tokens
+% and keep \fboxsep's scope local via added braces
+\def\PYG@tok@err{%
+ \def\PYG@bc##1{{\setlength{\fboxsep}{-\fboxrule}%
+ \fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}%
+}
+\def\PYG@tok@cs{%
+ \def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}%
+ \def\PYG@bc##1{{\setlength{\fboxsep}{0pt}%
+ \colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}%
+}%
-%% GRAPHICS
-%
-% \sphinxincludegraphics resizes images larger than the TeX \linewidth (which
-% is adjusted in indented environments), or taller than a certain maximal
-% height (usually \textheight and this is reduced in the environments which use
-% framed.sty to avoid infinite loop if image too tall).
-%
-% In case height or width options are present the rescaling is done
-% (since 2.0), in a way keeping the width:height ratio either native from
-% image or from the width and height options if both were present.
+%% TABLES
%
-\newdimen\spx@image@maxheight
-\AtBeginDocument{\spx@image@maxheight\textheight}
-
-% box scratch register
-\newbox\spx@image@box
-\newcommand*{\sphinxsafeincludegraphics}[2][]{%
- % #1 contains possibly width=, height=, but no scale= since 1.8.4
- \setbox\spx@image@box\hbox{\includegraphics[#1,draft]{#2}}%
- \in@false % use some handy boolean flag
- \ifdim \wd\spx@image@box>\linewidth
- \in@true % flag to remember to adjust options and set box dimensions
- % compute height which results from rescaling width to \linewidth
- % and keep current aspect ratio. multiply-divide in \numexpr uses
- % temporarily doubled precision, hence no overflow. (of course we
- % assume \ht is not a few sp's below \maxdimen...(about 16384pt).
- \edef\spx@image@rescaledheight % with sp units
- {\the\numexpr\ht\spx@image@box
- *\linewidth/\wd\spx@image@box sp}%
- \ifdim\spx@image@rescaledheight>\spx@image@maxheight
- % the rescaled height will be too big, so it is height which decides
- % the rescaling factor
- \def\spx@image@requiredheight{\spx@image@maxheight}% dimen register
- \edef\spx@image@requiredwidth % with sp units
- {\the\numexpr\wd\spx@image@box
- *\spx@image@maxheight/\ht\spx@image@box sp}%
- % TODO: decide if this commented-out block could be needed due to
- % rounding in numexpr operations going up
- % \ifdim\spx@image@requiredwidth>\linewidth
- % \def\spx@image@requiredwidth{\linewidth}% dimen register
- % \fi
- \else
- \def\spx@image@requiredwidth{\linewidth}% dimen register
- \let\spx@image@requiredheight\spx@image@rescaledheight% sp units
- \fi
- \else
- % width is ok, let's check height
- \ifdim\ht\spx@image@box>\spx@image@maxheight
- \in@true
- \edef\spx@image@requiredwidth % with sp units
- {\the\numexpr\wd\spx@image@box
- *\spx@image@maxheight/\ht\spx@image@box sp}%
- \def\spx@image@requiredheight{\spx@image@maxheight}% dimen register
- \fi
- \fi % end of check of width and height
- \ifin@
- \setbox\spx@image@box
- \hbox{\includegraphics
- [%#1,% contained only width and/or height and overruled anyhow
- width=\spx@image@requiredwidth,height=\spx@image@requiredheight]%
- {#2}}%
- % \includegraphics does not set box dimensions to the exactly
- % requested ones, see https://github.com/latex3/latex2e/issues/112
- \wd\spx@image@box\spx@image@requiredwidth
- \ht\spx@image@box\spx@image@requiredheight
- \leavevmode\box\spx@image@box
- \else
- % here we do not modify the options, no need to adjust width and height
- % on output, they will be computed exactly as with "draft" option
- \setbox\spx@image@box\box\voidb@x % clear memory
- \includegraphics[#1]{#2}%
- \fi
-}%
-% Use the "safe" one by default (2.0)
-\def\sphinxincludegraphics{\sphinxsafeincludegraphics}
+\input{sphinxlatextables.sty}
-%% FIGURE IN TABLE
+%% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS
%
-\newenvironment{sphinxfigure-in-table}[1][\linewidth]{%
- \def\@captype{figure}%
- \sphinxsetvskipsforfigintablecaption
- \begin{minipage}{#1}%
-}{\end{minipage}}
-% store the original \caption macro for usage with figures inside longtable
-% and tabulary cells. Make sure we get the final \caption in presence of
-% caption package, whether the latter was loaded before or after sphinx.
-\AtBeginDocument{%
- \let\spx@originalcaption\caption
- \@ifpackageloaded{caption}
- {\let\spx@ifcaptionpackage\@firstoftwo
- \caption@AtBeginDocument*{\let\spx@originalcaption\caption}%
-% in presence of caption package, drop our own \sphinxcaption whose aim was to
-% ensure same width of caption to all kinds of tables (tabular(y), longtable),
-% because caption package has its own width (or margin) option
- \def\sphinxcaption{\caption}%
- }%
- {\let\spx@ifcaptionpackage\@secondoftwo}%
-}
-% tabulary expands twice contents, we need to prevent double counter stepping
-\newcommand*\sphinxfigcaption
- {\ifx\equation$%$% this is trick to identify tabulary first pass
- \firstchoice@false\else\firstchoice@true\fi
- \spx@originalcaption }
-\newcommand*\sphinxsetvskipsforfigintablecaption
- {\abovecaptionskip\smallskipamount
- \belowcaptionskip\smallskipamount}
+\input{sphinxlatexnumfig.sty}
-%% CITATIONS
+%% LISTS
%
-\protected\def\sphinxcite{\cite}
+\input{sphinxlatexlists.sty}
+
%% FOOTNOTES
%
@@ -869,1295 +323,33 @@
p. #2, % <- space
\fi #1% no space
}
-% Support large numbered footnotes in minipage
-% But now obsolete due to systematic use of \savenotes/\spewnotes
-% when minipages are in use in the various macro definitions next.
+% support large numbered footnotes in minipage; but this is now obsolete
+% from systematic use of savenotes environment around minipages
\def\thempfootnote{\arabic{mpfootnote}}
+% This package is needed to support hyperlinked footnotes in tables and
+% framed contents, and to allow code-blocks in footnotes.
+\RequirePackage{sphinxpackagefootnote}
-%% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS
-
-% Everything is delayed to \begin{document} to allow hyperref patches into
-% \newcounter to solve duplicate label problems for internal hyperlinks to
-% code listings (literalblock counter). User or extension re-definitions of
-% \theliteralblock, et al., thus have also to be delayed. (changed at 3.5.0)
-\AtBeginDocument{%
-\ltx@ifundefined{c@chapter}
- {\newcounter{literalblock}}%
- {\newcounter{literalblock}[chapter]%
- \def\theliteralblock{\ifnum\c@chapter>\z@\arabic{chapter}.\fi
- \arabic{literalblock}}%
- }%
-\ifspx@opt@nonumfigreset
- \ltx@ifundefined{c@chapter}{}{%
- \@removefromreset{figure}{chapter}%
- \@removefromreset{table}{chapter}%
- \@removefromreset{literalblock}{chapter}%
- \ifspx@opt@mathnumfig
- \@removefromreset{equation}{chapter}%
- \fi
- }%
- \def\thefigure{\arabic{figure}}%
- \def\thetable {\arabic{table}}%
- \def\theliteralblock{\arabic{literalblock}}%
- \ifspx@opt@mathnumfig
- \def\theequation{\arabic{equation}}%
- \fi
-\else
-\let\spx@preAthefigure\@empty
-\let\spx@preBthefigure\@empty
-% \ifspx@opt@usespart % <-- LaTeX writer could pass such a 'usespart' boolean
-% % as sphinx.sty package option
-% If document uses \part, (triggered in Sphinx by latex_toplevel_sectioning)
-% LaTeX core per default does not reset chapter or section
-% counters at each part.
-% But if we modify this, we need to redefine \thechapter, \thesection to
-% include the part number and this will cause problems in table of contents
-% because of too wide numbering. Simplest is to do nothing.
-% \fi
-\ifnum\spx@opt@numfigreset>0
- \ltx@ifundefined{c@chapter}
- {}
- {\g@addto@macro\spx@preAthefigure{\ifnum\c@chapter>\z@\arabic{chapter}.}%
- \g@addto@macro\spx@preBthefigure{\fi}}%
-\fi
-\ifnum\spx@opt@numfigreset>1
- \@addtoreset{figure}{section}%
- \@addtoreset{table}{section}%
- \@addtoreset{literalblock}{section}%
- \ifspx@opt@mathnumfig
- \@addtoreset{equation}{section}%
- \fi%
- \g@addto@macro\spx@preAthefigure{\ifnum\c@section>\z@\arabic{section}.}%
- \g@addto@macro\spx@preBthefigure{\fi}%
-\fi
-\ifnum\spx@opt@numfigreset>2
- \@addtoreset{figure}{subsection}%
- \@addtoreset{table}{subsection}%
- \@addtoreset{literalblock}{subsection}%
- \ifspx@opt@mathnumfig
- \@addtoreset{equation}{subsection}%
- \fi%
- \g@addto@macro\spx@preAthefigure{\ifnum\c@subsection>\z@\arabic{subsection}.}%
- \g@addto@macro\spx@preBthefigure{\fi}%
-\fi
-\ifnum\spx@opt@numfigreset>3
- \@addtoreset{figure}{subsubsection}%
- \@addtoreset{table}{subsubsection}%
- \@addtoreset{literalblock}{subsubsection}%
- \ifspx@opt@mathnumfig
- \@addtoreset{equation}{subsubsection}%
- \fi%
- \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubsection>\z@\arabic{subsubsection}.}%
- \g@addto@macro\spx@preBthefigure{\fi}%
-\fi
-\ifnum\spx@opt@numfigreset>4
- \@addtoreset{figure}{paragraph}%
- \@addtoreset{table}{paragraph}%
- \@addtoreset{literalblock}{paragraph}%
- \ifspx@opt@mathnumfig
- \@addtoreset{equation}{paragraph}%
- \fi%
- \g@addto@macro\spx@preAthefigure{\ifnum\c@subparagraph>\z@\arabic{subparagraph}.}%
- \g@addto@macro\spx@preBthefigure{\fi}%
-\fi
-\ifnum\spx@opt@numfigreset>5
- \@addtoreset{figure}{subparagraph}%
- \@addtoreset{table}{subparagraph}%
- \@addtoreset{literalblock}{subparagraph}%
- \ifspx@opt@mathnumfig
- \@addtoreset{equation}{subparagraph}%
- \fi%
- \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubparagraph>\z@\arabic{subsubparagraph}.}%
- \g@addto@macro\spx@preBthefigure{\fi}%
-\fi
-\expandafter\g@addto@macro
-\expandafter\spx@preAthefigure\expandafter{\spx@preBthefigure}%
-\let\thefigure\spx@preAthefigure
-\let\thetable\spx@preAthefigure
-\let\theliteralblock\spx@preAthefigure
-\g@addto@macro\thefigure{\arabic{figure}}%
-\g@addto@macro\thetable{\arabic{table}}%
-\g@addto@macro\theliteralblock{\arabic{literalblock}}%
- \ifspx@opt@mathnumfig
- \let\theequation\spx@preAthefigure
- \g@addto@macro\theequation{\arabic{equation}}%
- \fi
-\fi
-}% end of big \AtBeginDocument
-
-%% LITERAL BLOCKS
-%
-% Based on use of "fancyvrb.sty"'s Verbatim.
-% - with framing allowing page breaks ("framed.sty")
-% - with breaking of long lines (exploits Pygments mark-up),
-% - with possibly of a top caption, non-separable by pagebreak.
-% - and usable inside tables or footnotes ("footnotehyper-sphinx").
-
-% Prior to Sphinx 1.5, \Verbatim and \endVerbatim were modified by Sphinx.
-% The aliases defined here are used in sphinxVerbatim environment and can
-% serve as hook-points with no need to modify \Verbatim itself.
-\let\OriginalVerbatim \Verbatim
-\let\endOriginalVerbatim\endVerbatim
-
-% for captions of literal blocks
-% at start of caption title
-\newcommand*{\fnum@literalblock}{\literalblockname\nobreakspace\theliteralblock}
-% this will be overwritten in document preamble by Babel translation
-\newcommand*{\literalblockname}{Listing }
-% file extension needed for \caption's good functioning, the file is created
-% only if a \listof{literalblock}{foo} command is encountered, which is
-% analogous to \listoffigures, but for the code listings (foo = chosen title.)
-\newcommand*{\ext@literalblock}{lol}
-
-\newif\ifspx@inframed % flag set if we are already in a framed environment
-% if forced use of minipage encapsulation is needed (e.g. table cells)
-\newif\ifsphinxverbatimwithminipage \sphinxverbatimwithminipagefalse
-
-% Framing macro for use with framed.sty's \FrameCommand
-% - it obeys current indentation,
-% - frame is \fboxsep separated from the contents,
-% - the contents use the full available text width,
-% - #1 = color of frame, #2 = color of background,
-% - #3 = above frame, #4 = below frame, #5 = within frame,
-% - #3 and #4 must be already typeset boxes; they must issue \normalcolor
-% or similar, else, they are under scope of color #1
-\long\def\spx@fcolorbox #1#2#3#4#5{%
- \hskip\@totalleftmargin
- \hskip-\fboxsep\hskip-\fboxrule
- % use of \color@b@x here is compatible with both xcolor.sty and color.sty
- \color@b@x {\color{#1}\spx@CustomFBox{#3}{#4}}{\color{#2}}{#5}%
- \hskip-\fboxsep\hskip-\fboxrule
- \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth
-}%
-% #1 = for material above frame, such as a caption or a "continued" hint
-% #2 = for material below frame, such as a caption or "continues on next page"
-% #3 = actual contents, which will be typeset with a background color
-\long\def\spx@CustomFBox#1#2#3{%
- \begingroup
- \setbox\@tempboxa\hbox{{#3}}% inner braces to avoid color leaks
- \vbox{#1% above frame
- % draw frame border _latest_ to avoid pdf viewer issue
- \kern\fboxrule
- \hbox{\kern\fboxrule
- \copy\@tempboxa
- \kern-\wd\@tempboxa\kern-\fboxrule
- \vrule\@width\fboxrule
- \kern\wd\@tempboxa
- \vrule\@width\fboxrule}%
- \kern-\dimexpr\ht\@tempboxa+\dp\@tempboxa+\fboxrule\relax
- \hrule\@height\fboxrule
- \kern\dimexpr\ht\@tempboxa+\dp\@tempboxa\relax
- \hrule\@height\fboxrule
- #2% below frame
- }%
- \endgroup
-}%
-\def\spx@fcolorbox@put@c#1{% hide width from framed.sty measuring
- \moveright\dimexpr\fboxrule+.5\wd\@tempboxa\hb@xt@\z@{\hss#1\hss}%
-}%
-\def\spx@fcolorbox@put@r#1{% right align with contents, width hidden
- \moveright\dimexpr\fboxrule+\wd\@tempboxa-\fboxsep\hb@xt@\z@{\hss#1}%
-}%
-\def\spx@fcolorbox@put@l#1{% left align with contents, width hidden
- \moveright\dimexpr\fboxrule+\fboxsep\hb@xt@\z@{#1\hss}%
-}%
-%
-\def\sphinxVerbatim@Continued
- {\csname spx@fcolorbox@put@\spx@opt@verbatimcontinuedalign\endcsname
- {\normalcolor\sphinxstylecodecontinued\literalblockcontinuedname}}%
-\def\sphinxVerbatim@Continues
- {\csname spx@fcolorbox@put@\spx@opt@verbatimcontinuesalign\endcsname
- {\normalcolor\sphinxstylecodecontinues\literalblockcontinuesname}}%
-\def\sphinxVerbatim@Title
- {\spx@fcolorbox@put@c{\unhcopy\sphinxVerbatim@TitleBox}}%
-\let\sphinxVerbatim@Before\@empty
-\let\sphinxVerbatim@After\@empty
-% Defaults are redefined in document preamble according to language
-\newcommand*\literalblockcontinuedname{continued from previous page}%
-\newcommand*\literalblockcontinuesname{continues on next page}%
-%
-\def\spx@verbatimfcolorbox{\spx@fcolorbox{VerbatimBorderColor}{VerbatimColor}}%
-\def\sphinxVerbatim@FrameCommand
- {\spx@verbatimfcolorbox\sphinxVerbatim@Before\sphinxVerbatim@After}%
-\def\sphinxVerbatim@FirstFrameCommand
- {\spx@verbatimfcolorbox\sphinxVerbatim@Before\sphinxVerbatim@Continues}%
-\def\sphinxVerbatim@MidFrameCommand
- {\spx@verbatimfcolorbox\sphinxVerbatim@Continued\sphinxVerbatim@Continues}%
-\def\sphinxVerbatim@LastFrameCommand
- {\spx@verbatimfcolorbox\sphinxVerbatim@Continued\sphinxVerbatim@After}%
-
-% For linebreaks inside Verbatim environment from package fancyvrb.
-\newbox\sphinxcontinuationbox
-\newbox\sphinxvisiblespacebox
-\newcommand*\sphinxafterbreak {\copy\sphinxcontinuationbox}
-
-% Take advantage of the already applied Pygments mark-up to insert
-% potential linebreaks for TeX processing.
-% {, <, #, %, $, ' and ": go to next line.
-% _, }, ^, &, >, -, ~, and \: stay at end of broken line.
-% Use of \textquotesingle for straight quote.
-% FIXME: convert this to package options ?
-\newcommand*\sphinxbreaksbeforelist {%
- \do\PYGZob\{\do\PYGZlt\<\do\PYGZsh\#\do\PYGZpc\%% {, <, #, %,
- \do\PYGZdl\$\do\PYGZdq\"% $, "
- \def\PYGZsq
- {\discretionary{}{\sphinxafterbreak\textquotesingle}{\textquotesingle}}% '
-}
-\newcommand*\sphinxbreaksafterlist {%
- \do\PYGZus\_\do\PYGZcb\}\do\PYGZca\^\do\PYGZam\&% _, }, ^, &,
- \do\PYGZgt\>\do\PYGZhy\-\do\PYGZti\~% >, -, ~
- \do\PYGZbs\\% \
-}
-\newcommand*\sphinxbreaksatspecials {%
- \def\do##1##2%
- {\def##1{\discretionary{}{\sphinxafterbreak\char`##2}{\char`##2}}}%
- \sphinxbreaksbeforelist
- \def\do##1##2%
- {\def##1{\discretionary{\char`##2}{\sphinxafterbreak}{\char`##2}}}%
- \sphinxbreaksafterlist
-}
-
-\def\sphinx@verbatim@nolig@list {\do \`}%
-% Some characters . , ; ? ! / are neither pygmentized nor "tex-escaped".
-% This macro makes them "active" and they will insert potential linebreaks.
-% Not compatible with math mode (cf \sphinxunactivateextras).
-\newcommand*\sphinxbreaksbeforeactivelist {}% none
-\newcommand*\sphinxbreaksafteractivelist {\do\.\do\,\do\;\do\?\do\!\do\/}
-\newcommand*\sphinxbreaksviaactive {%
- \def\do##1{\lccode`\~`##1%
- \lowercase{\def~}{\discretionary{}{\sphinxafterbreak\char`##1}{\char`##1}}%
- \catcode`##1\active}%
- \sphinxbreaksbeforeactivelist
- \def\do##1{\lccode`\~`##1%
- \lowercase{\def~}{\discretionary{\char`##1}{\sphinxafterbreak}{\char`##1}}%
- \catcode`##1\active}%
- \sphinxbreaksafteractivelist
- \lccode`\~`\~
-}
-
-% If the linebreak is at a space, the latter will be displayed as visible
-% space at end of first line, and a continuation symbol starts next line.
-\def\spx@verbatim@space {%
- \nobreak\hskip\z@skip
- \discretionary{\copy\sphinxvisiblespacebox}{\sphinxafterbreak}
- {\kern\fontdimen2\font}%
-}%
-
-% if the available space on page is less than \literalblockneedspace, insert pagebreak
-\newcommand{\sphinxliteralblockneedspace}{5\baselineskip}
-\newcommand{\sphinxliteralblockwithoutcaptionneedspace}{1.5\baselineskip}
-% The title (caption) is specified from outside as macro \sphinxVerbatimTitle.
-% \sphinxVerbatimTitle is reset to empty after each use of Verbatim.
-\newcommand*\sphinxVerbatimTitle {}
-% This box to typeset the caption before framed.sty multiple passes for framing.
-\newbox\sphinxVerbatim@TitleBox
-% This box to measure contents if nested as inner \MakeFramed requires then
-% minipage encapsulation but too long contents then break outer \MakeFramed
-\newbox\sphinxVerbatim@ContentsBox
-% This is a workaround to a "feature" of French lists, when literal block
-% follows immediately; usable generally (does only \par then), a priori...
-\newcommand*\sphinxvspacefixafterfrenchlists{%
- \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
-}
-% Holder macro for labels of literal blocks. Set-up by LaTeX writer.
-\newcommand*\sphinxLiteralBlockLabel {}
-\newcommand*\sphinxSetupCaptionForVerbatim [1]
-{%
- \sphinxvspacefixafterfrenchlists
- \needspace{\sphinxliteralblockneedspace}%
-% insert a \label via \sphinxLiteralBlockLabel
-% reset to normal the color for the literal block caption
- \def\sphinxVerbatimTitle
- {\py@NormalColor\sphinxcaption{\sphinxLiteralBlockLabel #1}}%
-}
-\newcommand*\sphinxSetupCodeBlockInFootnote {%
- \fvset{fontsize=\footnotesize}\let\caption\sphinxfigcaption
- \sphinxverbatimwithminipagetrue % reduces vertical spaces
- % we counteract (this is in a group) the \@normalsize from \caption
- \let\normalsize\footnotesize\let\@parboxrestore\relax
- \def\spx@abovecaptionskip{\sphinxverbatimsmallskipamount}%
-}
-\newcommand*{\sphinxverbatimsmallskipamount}{\smallskipamount}
-% serves to implement line highlighting and line wrapping
-\newcommand\sphinxFancyVerbFormatLine[1]{%
- \expandafter\sphinx@verbatim@checkifhl\expandafter{\the\FV@CodeLineNo}%
- \ifin@
- \sphinxVerbatimHighlightLine{#1}%
- \else
- \sphinxVerbatimFormatLine{#1}%
- \fi
-}%
-\newcommand\sphinxVerbatimHighlightLine[1]{%
- \edef\sphinxrestorefboxsep{\fboxsep\the\fboxsep\relax}%
- \fboxsep0pt\relax % cf LaTeX bug graphics/4524
- \colorbox{sphinxVerbatimHighlightColor}%
- {\sphinxrestorefboxsep\sphinxVerbatimFormatLine{#1}}%
- % no need to restore \fboxsep here, as this ends up in a \hbox from fancyvrb
-}%
-% \sphinxVerbatimFormatLine will be set locally to one of those two:
-\newcommand\sphinxVerbatimFormatLineWrap{%
- \hsize\linewidth
- \ifspx@opt@verbatimforcewraps
- \expandafter\spx@verb@FormatLineForceWrap
- \else\expandafter\spx@verb@FormatLineWrap
- \fi
-}%
-\newcommand\sphinxVerbatimFormatLineNoWrap[1]{\hb@xt@\linewidth{\strut #1\hss}}%
-\long\def\spx@verb@FormatLineWrap#1{%
- \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
- \doublehyphendemerits\z@\finalhyphendemerits\z@
- \strut #1\strut}%
-}%
-%
-% The normal line wrapping allows breaks at spaces and ascii non
-% letters, non digits. The \raggedright above means there will be
-% an overfilled line only if some non-breakable "word" was
-% encountered, which is longer than a line (it is moved always to
-% be on its own on a new line).
-%
-% The "forced" line wrapping will parse the tokens to add potential
-% breakpoints at each character. As some strings are highlighted,
-% we have to apply the highlighting character per character, which
-% requires to manipulate the output of the Pygments LaTeXFormatter.
-%
-% Doing this at latex level is complicated. The contents should
-% be as expected: i.e. some active characters from
-% \sphinxbreaksviaactive, some Pygments character escapes such as
-% \PYGZdl{}, and the highlighting \PYG macro with always 2
-% arguments. No other macros should be there, except perhaps
-% zero-parameter macros. In particular:
-% - the texcomments Pygments option must be set to False
-%
-% With pdflatex, Unicode input gives multi-bytes characters
-% where the first byte is active. We support the "utf8" macros
-% only. "utf8x" is not supported.
-%
-% The highlighting macro \PYG will be applied character per
-% character. Highlighting via a colored background gives thus a
-% chain of small colored boxes which may cause some artefact in
-% some pdf viewers. Can't do anything here if we do want the line
-% break to be possible.
-%
-% First a measurement step is done of what would the standard line
-% wrapping give (i.e line breaks only at spaces and non-letter,
-% non-digit ascii characters), cf TeX by Topic for the basic
-% dissecting technique: TeX unfortunately when building a vertical
-% box does not store in an accessible way what was the maximal
-% line-width during paragraph building.
-%
-% If the max width exceeds the linewidth by more than verbatimmaxoverfull
-% character widths, or if the min width plus verbatimmaxunderfull character
-% widths is inferior to linewidth, then we apply the "force wrapping" with
-% potential line break at each character, else we don't.
-\long\def\spx@verb@FormatLineForceWrap#1{%
- % \spx@image@box is a scratch box register that we can use here
- \global\let\spx@verb@maxwidth\z@
- \global\let\spx@verb@minwidth\linewidth
- \setbox\spx@image@box
- \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
- \doublehyphendemerits\z@\finalhyphendemerits\z@
- \strut #1\strut\@@par
- \spx@verb@getwidths}%
- \ifdim\spx@verb@maxwidth>
- \dimexpr\linewidth+\spx@opt@verbatimmaxoverfull\fontcharwd\font`X \relax
- \spx@verb@FormatLineWrap{\spx@verb@wrapPYG #1\spx@verb@wrapPYG}%
- \else
- \ifdim\spx@verb@minwidth<
- \dimexpr\linewidth-\spx@opt@verbatimmaxunderfull\fontcharwd\font`X \relax
- \spx@verb@FormatLineWrap{\spx@verb@wrapPYG #1\spx@verb@wrapPYG}%
- \else
- \spx@verb@FormatLineWrap{#1}%
- \fi\fi
-}%
-% auxiliary paragraph dissector to get max and min widths
-\newbox\spx@scratchbox
-\def\spx@verb@getwidths {%
- \unskip\unpenalty
- \setbox\spx@scratchbox\lastbox
- \ifvoid\spx@scratchbox
- \else
- \setbox\spx@scratchbox\hbox{\unhbox\spx@scratchbox}%
- \ifdim\spx@verb@maxwidth<\wd\spx@scratchbox
- \xdef\spx@verb@maxwidth{\number\wd\spx@scratchbox sp}%
- \fi
- \ifdim\spx@verb@minwidth>\wd\spx@scratchbox
- \xdef\spx@verb@minwidth{\number\wd\spx@scratchbox sp}%
- \fi
- \expandafter\spx@verb@getwidths
- \fi
-}%
-% auxiliary macros to implement "cut long line even in middle of word"
-\catcode`Z=3 % safe delimiter
-\def\spx@verb@wrapPYG{%
- \futurelet\spx@nexttoken\spx@verb@wrapPYG@i
-}%
-\def\spx@verb@wrapPYG@i{%
- \ifx\spx@nexttoken\spx@verb@wrapPYG\let\next=\@gobble\else
- \ifx\spx@nexttoken\PYG\let\next=\spx@verb@wrapPYG@PYG@onebyone\else
- \discretionary{}{\sphinxafterbreak}{}%
- \let\next\spx@verb@wrapPYG@ii
- \fi\fi
- \next
-}%
-% Let's recognize active characters. We don't support utf8x only utf8.
-% And here #1 should not have picked up (non empty) braced contents
-\long\def\spx@verb@wrapPYG@ii#1{%
- \ifcat\noexpand~\noexpand#1\relax% active character
- \expandafter\spx@verb@wrapPYG@active
- \else % non-active character, control sequence such as \PYGZdl, or empty
- \expandafter\spx@verb@wrapPYG@one
- \fi {#1}%
-}%
-\long\def\spx@verb@wrapPYG@active#1{%
-% Let's hope expansion of active character does not really require arguments,
-% as we certainly don't want to go into expanding upfront token stream anyway.
- \expandafter\spx@verb@wrapPYG@iii#1{}{}{}{}{}{}{}{}{}Z#1%
-}%
-\long\def\spx@verb@wrapPYG@iii#1#2Z{%
- \ifx\UTFviii@four@octets#1\let\next=\spx@verb@wrapPYG@four\else
- \ifx\UTFviii@three@octets#1\let\next=\spx@verb@wrapPYG@three\else
- \ifx\UTFviii@two@octets#1\let\next=\spx@verb@wrapPYG@two\else
- \let\next=\spx@verb@wrapPYG@one
- \fi\fi\fi
- \next
-}%
-\long\def\spx@verb@wrapPYG@one #1{#1\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
-\long\def\spx@verb@wrapPYG@two #1#2{#1#2\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
-\long\def\spx@verb@wrapPYG@three #1#2#3{#1#2#3\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
-\long\def\spx@verb@wrapPYG@four #1#2#3#4{#1#2#3#4\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
-% Replace \PYG by itself applied one character at a time! This way breakpoints
-% can be inserted.
-\def\spx@verb@wrapPYG@PYG@onebyone#1#2#3{% #1 = \PYG, #2 = highlight spec, #3 = tokens
- \def\spx@verb@wrapPYG@PYG@spec{{#2}}%
- \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i#3Z%
-}%
-\def\spx@verb@wrapPYG@PYG@i{%
- \ifx\spx@nexttokenZ\let\next=\spx@verb@wrapPYG@PYG@done\else
- \discretionary{}{\sphinxafterbreak}{}%
- \let\next\spx@verb@wrapPYG@PYG@ii
- \fi
- \next
-}%
-\def\spx@verb@wrapPYG@PYG@doneZ{\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
-\long\def\spx@verb@wrapPYG@PYG@ii#1{%
- \ifcat\noexpand~\noexpand#1\relax% active character
- \expandafter\spx@verb@wrapPYG@PYG@active
- \else % non-active character, control sequence such as \PYGZdl, or empty
- \expandafter\spx@verb@wrapPYG@PYG@one
- \fi {#1}%
-}%
-\long\def\spx@verb@wrapPYG@PYG@active#1{%
-% Let's hope expansion of active character does not really require arguments,
-% as we certainly don't want to go into expanding upfront token stream anyway.
- \expandafter\spx@verb@wrapPYG@PYG@iii#1{}{}{}{}{}{}{}{}{}Z#1%
-}%
-\long\def\spx@verb@wrapPYG@PYG@iii#1#2Z{%
- \ifx\UTFviii@four@octets#1\let\next=\spx@verb@wrapPYG@PYG@four\else
- \ifx\UTFviii@three@octets#1\let\next=\spx@verb@wrapPYG@PYG@three\else
- \ifx\UTFviii@two@octets#1\let\next=\spx@verb@wrapPYG@PYG@two\else
- \let\next=\spx@verb@wrapPYG@PYG@one
- \fi\fi\fi
- \next
-}%
-\long\def\spx@verb@wrapPYG@PYG@one#1{%
- \expandafter\PYG\spx@verb@wrapPYG@PYG@spec{#1}%
- \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i
-}%
-\long\def\spx@verb@wrapPYG@PYG@two#1#2{%
- \expandafter\PYG\spx@verb@wrapPYG@PYG@spec{#1#2}%
- \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i
-}%
-\long\def\spx@verb@wrapPYG@PYG@three#1#2#3{%
- \expandafter\PYG\spx@verb@wrapPYG@PYG@spec{#1#2#3}%
- \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i
-}%
-\long\def\spx@verb@wrapPYG@PYG@four#1#2#3#4{%
- \expandafter\PYG\spx@verb@wrapPYG@PYG@spec{#1#2#3#4}%
- \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i
-}%
-\catcode`Z 11 %
-%
-\g@addto@macro\FV@SetupFont{%
- \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
- \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
-}%
-\newenvironment{sphinxVerbatim}{%
- % first, let's check if there is a caption
- \ifx\sphinxVerbatimTitle\empty
- \sphinxvspacefixafterfrenchlists
- \parskip\z@skip
- \vskip\sphinxverbatimsmallskipamount
- % there was no caption. Check if nevertheless a label was set.
- \ifx\sphinxLiteralBlockLabel\empty\else
- % we require some space to be sure hyperlink target from \phantomsection
- % will not be separated from upcoming verbatim by a page break
- \needspace{\sphinxliteralblockwithoutcaptionneedspace}%
- \phantomsection\sphinxLiteralBlockLabel
- \fi
- \else
- \parskip\z@skip
- \if t\spx@opt@literalblockcappos
- \vskip\spx@abovecaptionskip
- \def\sphinxVerbatim@Before
- {\sphinxVerbatim@Title\nointerlineskip
- \kern\dimexpr-\dp\strutbox+\sphinxbelowcaptionspace
- % if no frame (code-blocks inside table cells), remove
- % the "verbatimsep" whitespace from the top (better visually)
- \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi
- % caption package adds \abovecaptionskip vspace, remove it
- \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax}%
- \else
- \vskip\sphinxverbatimsmallskipamount
- \def\sphinxVerbatim@After
- {\nointerlineskip\kern\dimexpr\dp\strutbox
- \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi
- \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax
- \sphinxVerbatim@Title}%
- \fi
- \def\@captype{literalblock}%
- \capstart
- % \sphinxVerbatimTitle must reset color
- \setbox\sphinxVerbatim@TitleBox
- \hbox{\begin{minipage}{\linewidth}%
- % caption package may detect wrongly if top or bottom, so we help it
- \spx@ifcaptionpackage
- {\caption@setposition{\spx@opt@literalblockcappos}}{}%
- \sphinxVerbatimTitle
- \end{minipage}}%
- \fi
- \global\let\sphinxLiteralBlockLabel\empty
- \global\let\sphinxVerbatimTitle\empty
- \fboxsep\sphinxverbatimsep \fboxrule\sphinxverbatimborder
- \ifspx@opt@verbatimwithframe\else\fboxrule\z@\fi
- \let\FrameCommand \sphinxVerbatim@FrameCommand
- \let\FirstFrameCommand\sphinxVerbatim@FirstFrameCommand
- \let\MidFrameCommand \sphinxVerbatim@MidFrameCommand
- \let\LastFrameCommand \sphinxVerbatim@LastFrameCommand
- \ifspx@opt@verbatimhintsturnover\else
- \let\sphinxVerbatim@Continued\@empty
- \let\sphinxVerbatim@Continues\@empty
- \fi
- \ifspx@opt@verbatimwrapslines
- % fancyvrb's Verbatim puts each input line in (unbreakable) horizontal boxes.
- % This customization wraps each line from the input in a \vtop, thus
- % allowing it to wrap and display on two or more lines in the latex output.
- % - The codeline counter will be increased only once.
- % - The wrapped material will not break across pages, it is impossible
- % to achieve this without extensive rewrite of fancyvrb.
- % - The (not used in sphinx) obeytabs option to Verbatim is
- % broken by this change (showtabs and tabspace work).
- \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineWrap
- \let\FV@Space\spx@verbatim@space
- % Allow breaks at special characters using \PYG... macros.
- \sphinxbreaksatspecials
- % Breaks at punctuation characters . , ; ? ! and / (needs catcode activation)
- \fvset{codes*=\sphinxbreaksviaactive}%
- \else % end of conditional code for wrapping long code lines
- \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineNoWrap
- \fi
- \let\FancyVerbFormatLine\sphinxFancyVerbFormatLine
- \VerbatimEnvironment
- % workaround to fancyvrb's check of current list depth
- \def\@toodeep {\advance\@listdepth\@ne}%
- % The list environment is needed to control perfectly the vertical space.
- % Note: \OuterFrameSep used by framed.sty is later set to \topsep hence 0pt.
- % - if caption: distance from last text baseline to caption baseline is
- % A+(B-F)+\ht\strutbox, A = \abovecaptionskip (default 10pt), B =
- % \baselineskip, F is the framed.sty \FrameHeightAdjust macro, default 6pt.
- % Formula valid for F < 10pt.
- % - distance of baseline of caption to top of frame is like for tables:
- % \sphinxbelowcaptionspace (=0.5\baselineskip)
- % - if no caption: distance of last text baseline to code frame is S+(B-F),
- % with S = \sphinxverbatimtopskip (=\smallskip)
- % - and distance from bottom of frame to next text baseline is
- % \baselineskip+\parskip.
- % The \trivlist is used to avoid possible "too deeply nested" error.
- \itemsep \z@skip
- \topsep \z@skip
- \partopsep \z@skip
- % trivlist will set \parsep to \parskip (which itself is set to zero above)
- % \leftmargin will be set to zero by trivlist
- \rightmargin\z@
- \parindent \z@% becomes \itemindent. Default zero, but perhaps overwritten.
- \trivlist\item\relax
- \ifspx@inframed\setbox\sphinxVerbatim@ContentsBox\vbox\bgroup
- \@setminipage\hsize\linewidth
- % use bulk of minipage paragraph shape restores (this is needed
- % in indented contexts, at least for some)
- \textwidth\hsize \columnwidth\hsize \@totalleftmargin\z@
- \leftskip\z@skip \rightskip\z@skip \@rightskip\z@skip
- \else
- \ifsphinxverbatimwithminipage\noindent\begin{minipage}{\linewidth}\fi
- \MakeFramed {% adapted over from framed.sty's snugshade environment
- \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage
- }%
- \fi
- % For grid placement from \strut's in \FancyVerbFormatLine
- \lineskip\z@skip
- % active comma should not be overwritten by \@noligs
- \ifspx@opt@verbatimwrapslines
- \let\verbatim@nolig@list \sphinx@verbatim@nolig@list
- \fi
- % will fetch its optional arguments if any
- \OriginalVerbatim
-}
-{%
- \endOriginalVerbatim
- \ifspx@inframed
- \egroup % finish \sphinxVerbatim@ContentsBox vbox
- \nobreak % update page totals
- \ifdim\dimexpr\ht\sphinxVerbatim@ContentsBox+
- \dp\sphinxVerbatim@ContentsBox+
- \ht\sphinxVerbatim@TitleBox+
- \dp\sphinxVerbatim@TitleBox+
- 2\fboxsep+2\fboxrule+
- % try to account for external frame parameters
- \FrameSep+\FrameRule+
- % Usage here of 2 baseline distances is empirical.
- % In border case where code-block fits barely in remaining space,
- % it gets framed and looks good but the outer frame may continue
- % on top of next page and give (if no contents after code-block)
- % an empty framed line, as testing showed.
- 2\baselineskip+
- % now add all to accumulated page totals and compare to \pagegoal
- \pagetotal+\pagedepth>\pagegoal
- % long contents: do not \MakeFramed. Do make a caption (either before or
- % after) if title exists. Continuation hints across pagebreaks dropped.
- % FIXME? a bottom caption may end up isolated at top of next page
- % (no problem with a top caption, which is default)
- \spx@opt@verbatimwithframefalse
- \def\sphinxVerbatim@Title{\noindent\box\sphinxVerbatim@TitleBox\par}%
- \sphinxVerbatim@Before
- \noindent\unvbox\sphinxVerbatim@ContentsBox\par
- \sphinxVerbatim@After
- \else
- % short enough contents: use \MakeFramed. As it is nested, this requires
- % minipage encapsulation.
- \noindent\begin{minipage}{\linewidth}%
- \MakeFramed {% Use it now with the fetched contents
- \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage
- }%
- \unvbox\sphinxVerbatim@ContentsBox
- % some of this may be superfluous:
- \par\unskip\@minipagefalse\endMakeFramed
- \end{minipage}%
- \fi
- \else % non-nested \MakeFramed
- \par\unskip\@minipagefalse\endMakeFramed % from framed.sty snugshade
- \ifsphinxverbatimwithminipage\end{minipage}\fi
- \fi
- \endtrivlist
-}
-\newenvironment {sphinxVerbatimNoFrame}
- {\spx@opt@verbatimwithframefalse
- \VerbatimEnvironment
- \begin{sphinxVerbatim}}
- {\end{sphinxVerbatim}}
-\newenvironment {sphinxVerbatimintable}
- {% don't use a frame if in a table cell
- \spx@opt@verbatimwithframefalse
- \sphinxverbatimwithminipagetrue
- % the literal block caption uses \sphinxcaption which is wrapper of \caption,
- % but \caption must be modified because longtable redefines it to work only
- % for the own table caption, and tabulary has multiple passes
- \let\caption\sphinxfigcaption
- % reduce above caption skip
- \def\spx@abovecaptionskip{\sphinxverbatimsmallskipamount}%
- \VerbatimEnvironment
- \begin{sphinxVerbatim}}
- {\end{sphinxVerbatim}}
-
-
-%% PARSED LITERALS
-% allow long lines to wrap like they do in code-blocks
-
-% this should be kept in sync with definitions in sphinx.util.texescape
-\newcommand*\sphinxbreaksattexescapedchars{%
- \def\do##1##2% put potential break point before character
- {\def##1{\discretionary{}{\sphinxafterbreak\char`##2}{\char`##2}}}%
- \do\{\{\do\textless\<\do\#\#\do\%\%\do\$\$% {, <, #, %, $
- \def\do##1##2% put potential break point after character
- {\def##1{\discretionary{\char`##2}{\sphinxafterbreak}{\char`##2}}}%
- \do\_\_\do\}\}\do\textasciicircum\^\do\&\&% _, }, ^, &,
- \do\textgreater\>\do\textasciitilde\~% >, ~
- \do\textbackslash\\% \
-}
-\newcommand*\sphinxbreaksviaactiveinparsedliteral{%
- \sphinxbreaksviaactive % by default handles . , ; ? ! /
- \lccode`\~`\~ %
- % update \dospecials as it is used by \url
- % but deactivation will already have been done hence this is unneeded:
- % \expandafter\def\expandafter\dospecials\expandafter{\dospecials
- % \sphinxbreaksbeforeactivelist\sphinxbreaksafteractivelist\do\-}%
-}
-\newcommand*\sphinxbreaksatspaceinparsedliteral{%
- \lccode`~32 \lowercase{\let~}\spx@verbatim@space\lccode`\~`\~
-}
-\newcommand*{\sphinxunactivateextras}{\let\do\@makeother
- \sphinxbreaksbeforeactivelist\sphinxbreaksafteractivelist}%
-% the \catcode13=5\relax (deactivate end of input lines) is left to callers
-\newcommand*{\sphinxunactivateextrasandspace}{\catcode32=10\relax
- \sphinxunactivateextras}%
-% now for the modified alltt environment
-\newenvironment{sphinxalltt}
-{% at start of next line to workaround Emacs/AUCTeX issue with this file
-\begin{alltt}%
- \ifspx@opt@parsedliteralwraps
- \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
- \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
- \sphinxbreaksattexescapedchars
- \sphinxbreaksviaactiveinparsedliteral
- \sphinxbreaksatspaceinparsedliteral
-% alltt takes care of the ' as derivative ("prime") in math mode
- \everymath\expandafter{\the\everymath\sphinxunactivateextrasandspace
- \catcode`\<=12\catcode`\>=12\catcode`\^=7\catcode`\_=8 }%
-% not sure if displayed math (align,...) can end up in parsed-literal, anyway
- \everydisplay\expandafter{\the\everydisplay
- \catcode13=5 \sphinxunactivateextrasandspace
- \catcode`\<=12\catcode`\>=12\catcode`\^=7\catcode`\_=8 }%
- \fi }
-{\end{alltt}}
-
-% Protect \href's first argument in contexts such as sphinxalltt (or
-% \sphinxcode). Sphinx uses \#, \%, \& ... always inside \sphinxhref.
-\protected\def\sphinxhref#1#2{{%
- \sphinxunactivateextrasandspace % never do \scantokens with active space!
-% for the \endlinechar business, https://github.com/latex3/latex2e/issues/286
- \endlinechar\m@ne\everyeof{{\endlinechar13 #2}}% keep catcode regime for #2
- \scantokens{\href{#1}}% normalise it for #1 during \href expansion
-}}
-% Same for \url. And also \nolinkurl for coherence.
-\protected\def\sphinxurl#1{{%
- \sphinxunactivateextrasandspace\everyeof{}% (<- precaution for \scantokens)
- \endlinechar\m@ne\scantokens{\url{#1}}%
-}}
-\protected\def\sphinxnolinkurl#1{{%
- \sphinxunactivateextrasandspace\everyeof{}%
- \endlinechar\m@ne\scantokens{\nolinkurl{#1}}%
-}}
-
-
-%% TOPIC AND CONTENTS BOXES
-%
-% Again based on use of "framed.sty", this allows breakable framed boxes.
-\long\def\spx@ShadowFBox#1{%
- \leavevmode\begingroup
- % first we frame the box #1
- \setbox\@tempboxa
- \hbox{\vrule\@width\sphinxshadowrule
- \vbox{\hrule\@height\sphinxshadowrule
- \kern\sphinxshadowsep
- \hbox{\kern\sphinxshadowsep #1\kern\sphinxshadowsep}%
- \kern\sphinxshadowsep
- \hrule\@height\sphinxshadowrule}%
- \vrule\@width\sphinxshadowrule}%
- % Now we add the shadow, like \shadowbox from fancybox.sty would do
- \dimen@\dimexpr.5\sphinxshadowrule+\sphinxshadowsize\relax
- \hbox{\vbox{\offinterlineskip
- \hbox{\copy\@tempboxa\kern-.5\sphinxshadowrule
- % add shadow on right side
- \lower\sphinxshadowsize
- \hbox{\vrule\@height\ht\@tempboxa \@width\dimen@}%
- }%
- \kern-\dimen@ % shift back vertically to bottom of frame
- % and add shadow at bottom
- \moveright\sphinxshadowsize
- \vbox{\hrule\@width\wd\@tempboxa \@height\dimen@}%
- }%
- % move left by the size of right shadow so shadow adds no width
- \kern-\sphinxshadowsize
- }%
- \endgroup
-}
-
-% use framed.sty to allow page breaks in frame+shadow
-% works well inside Lists and Quote-like environments
-% produced by ``topic'' directive (or local contents)
-% could nest if LaTeX writer authorized it
-\newenvironment{sphinxShadowBox}
- {\def\FrameCommand {\spx@ShadowFBox }%
- \advance\spx@image@maxheight
- -\dimexpr2\sphinxshadowrule
- +2\sphinxshadowsep
- +\sphinxshadowsize
- +\baselineskip\relax
- % configure framed.sty not to add extra vertical spacing
- \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}%
- % the \trivlist will add the vertical spacing on top and bottom which is
- % typical of center environment as used in Sphinx <= 1.4.1
- % the \noindent has the effet of an extra blank line on top, to
- % imitate closely the layout from Sphinx <= 1.4.1; the \FrameHeightAdjust
- % will put top part of frame on this baseline.
- \def\FrameHeightAdjust {\baselineskip}%
- % use package footnote to handle footnotes
- \savenotes
- \trivlist\item\noindent
- % use a minipage if we are already inside a framed environment
- \ifspx@inframed\begin{minipage}{\linewidth}\fi
- \MakeFramed {\spx@inframedtrue
- % framed.sty puts into "\width" the added width (=2shadowsep+2shadowrule)
- % adjust \hsize to what the contents must use
- \advance\hsize-\width
- % adjust LaTeX parameters to behave properly in indented/quoted contexts
- \FrameRestore
- % typeset the contents as in a minipage (Sphinx <= 1.4.1 used a minipage and
- % itemize/enumerate are therein typeset more tightly, we want to keep
- % that). We copy-paste from LaTeX source code but don't do a real minipage.
- \@pboxswfalse
- \let\@listdepth\@mplistdepth \@mplistdepth\z@
- \@minipagerestore
- \@setminipage
- }%
- }%
- {% insert the "endminipage" code
- \par\unskip
- \@minipagefalse
- \endMakeFramed
- \ifspx@inframed\end{minipage}\fi
- \endtrivlist
- % output the stored footnotes
- \spewnotes
- }
-
-
-%% NOTICES AND ADMONITIONS
-%
-% Some are quite plain
-% the spx@notice@bordercolor etc are set in the sphinxadmonition environment
-\newenvironment{sphinxlightbox}{%
- \par
- \noindent{\color{spx@notice@bordercolor}%
- \rule{\linewidth}{\spx@notice@border}}\par\nobreak
- {\parskip\z@skip\noindent}%
- }
- {%
- % counteract previous possible negative skip (French lists!):
- % (we can't cancel that any earlier \vskip introduced a potential pagebreak)
- \sphinxvspacefixafterfrenchlists
- \nobreak\vbox{\noindent\kern\@totalleftmargin
- {\color{spx@notice@bordercolor}%
- \rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
- {\linewidth}{\spx@notice@border}}\hss}\allowbreak
- }% end of sphinxlightbox environment definition
-% may be renewenvironment'd by user for complete customization
-\newenvironment{sphinxnote}[1]
- {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
-\newenvironment{sphinxhint}[1]
- {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
-\newenvironment{sphinximportant}[1]
- {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
-\newenvironment{sphinxtip}[1]
- {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
-% or just use the package options
-% these are needed for common handling by notice environment of lightbox
-% and heavybox but they are currently not used by lightbox environment
-% and there is consequently no corresponding package option
-\definecolor{sphinxnoteBgColor}{rgb}{1,1,1}
-\definecolor{sphinxhintBgColor}{rgb}{1,1,1}
-\definecolor{sphinximportantBgColor}{rgb}{1,1,1}
-\definecolor{sphinxtipBgColor}{rgb}{1,1,1}
-
-% Others get more distinction
-% Code adapted from framed.sty's "snugshade" environment.
-% Nesting works (inner frames do not allow page breaks).
-\newenvironment{sphinxheavybox}{\par
- \setlength{\FrameRule}{\spx@notice@border}%
- \setlength{\FrameSep}{\dimexpr.6\baselineskip-\FrameRule\relax}
- \advance\spx@image@maxheight
- -\dimexpr2\FrameRule
- +2\FrameSep
- +\baselineskip\relax % will happen again if nested, needed indeed!
- % configure framed.sty's parameters to obtain same vertical spacing
- % as for "light" boxes. We need for this to manually insert parskip glue and
- % revert a skip done by framed before the frame.
- \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}%
- \vspace{\FrameHeightAdjust}
- % copied/adapted from framed.sty's snugshade
- \def\FrameCommand##1{\hskip\@totalleftmargin
- \fboxsep\FrameSep \fboxrule\FrameRule
- \fcolorbox{spx@notice@bordercolor}{spx@notice@bgcolor}{##1}%
- \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
- \savenotes
- % use a minipage if we are already inside a framed environment
- \ifspx@inframed
- \noindent\begin{minipage}{\linewidth}
- \else
- % handle case where notice is first thing in a list item (or is quoted)
- \if@inlabel
- \noindent\par\vspace{-\baselineskip}
- \else
- \vspace{\parskip}
- \fi
- \fi
- \MakeFramed {\spx@inframedtrue
- \advance\hsize-\width \@totalleftmargin\z@ \linewidth\hsize
- % minipage initialization copied from LaTeX source code.
- \@pboxswfalse
- \let\@listdepth\@mplistdepth \@mplistdepth\z@
- \@minipagerestore
- \@setminipage }%
- }
- {%
- \par\unskip
- \@minipagefalse
- \endMakeFramed
- \ifspx@inframed\end{minipage}\fi
- % set footnotes at bottom of page
- \spewnotes
- % arrange for similar spacing below frame as for "light" boxes.
- \vskip .4\baselineskip
- }% end of sphinxheavybox environment definition
-% may be renewenvironment'd by user for complete customization
-\newenvironment{sphinxwarning}[1]
- {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
-\newenvironment{sphinxcaution}[1]
- {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
-\newenvironment{sphinxattention}[1]
- {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
-\newenvironment{sphinxdanger}[1]
- {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
-\newenvironment{sphinxerror}[1]
- {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
-% or just use package options
-
-% the \colorlet of xcolor (if at all loaded) is overkill for our use case
-\newcommand{\sphinxcolorlet}[2]
- {\expandafter\let\csname\@backslashchar color@#1\expandafter\endcsname
- \csname\@backslashchar color@#2\endcsname }
-
-% the main dispatch for all types of notices
-\newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
- % can't use #1 directly in definition of end part
- \def\spx@noticetype {#1}%
- % set parameters of heavybox/lightbox
- \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
- \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
- \spx@notice@border \dimexpr\csname spx@opt@#1border\endcsname\relax
- % start specific environment, passing the heading as argument
- \begin{sphinx#1}{#2}}
- % workaround some LaTeX "feature" of \end command
- {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
-
-
-%% PYTHON DOCS MACROS AND ENVIRONMENTS
-% (some macros here used by \maketitle in sphinxmanual.cls and sphinxhowto.cls)
-
-% \moduleauthor{name}{email}
-\newcommand{\moduleauthor}[2]{}
-
-% \sectionauthor{name}{email}
-\newcommand{\sectionauthor}[2]{}
-
-% Allow the release number to be specified independently of the
-% \date{}. This allows the date to reflect the document's date and
-% release to specify the release that is documented.
-%
-\newcommand{\py@release}{\releasename\space\version}
-\newcommand{\version}{}% part of \py@release, used by title page and headers
-% \releaseinfo is used on titlepage (sphinxmanual.cls, sphinxhowto.cls)
-\newcommand{\releaseinfo}{}
-\newcommand{\setreleaseinfo}[1]{\renewcommand{\releaseinfo}{#1}}
-% this is inserted via template and #1=release config variable
-\newcommand{\release}[1]{\renewcommand{\version}{#1}}
-% this is defined by template to 'releasename' latex_elements key
-\newcommand{\releasename}{}
-% Fix issue in case release and releasename deliberately left blank
-\newcommand{\sphinxheadercomma}{, }% used in fancyhdr header definition
-\newcommand{\sphinxifemptyorblank}[1]{%
-% test after one expansion of macro #1 if contents is empty or spaces
- \if&\expandafter\@firstofone\detokenize\expandafter{#1}&%
- \expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}%
-\AtBeginDocument {%
- \sphinxifemptyorblank{\releasename}
- {\sphinxifemptyorblank{\version}{\let\sphinxheadercomma\empty}{}}
- {}%
-}%
-
-% Allow specification of the author's address separately from the
-% author's name. This can be used to format them differently, which
-% is a good thing.
-%
-\newcommand{\py@authoraddress}{}
-\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
-
-% {fulllineitems} is the main environment for object descriptions.
+%% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS
%
-\newcommand{\py@itemnewline}[1]{%
- \kern\labelsep
- \@tempdima\linewidth
- \advance\@tempdima \labelwidth\makebox[\@tempdima][l]{#1}%
- \kern-\labelsep
-}
-
-\newenvironment{fulllineitems}{%
- \begin{list}{}{\labelwidth \leftmargin
- \rightmargin \z@ \topsep -\parskip \partopsep \parskip
- \itemsep -\parsep
- \let\makelabel=\py@itemnewline}%
-}{\end{list}}
+\input{sphinxlatexindbibtoc.sty}
-% Signatures, possibly multi-line
-%
-\newlength{\py@argswidth}
-\newcommand{\py@sigparams}[2]{%
- \parbox[t]{\py@argswidth}{#1\sphinxcode{)}#2}}
-\newcommand{\pysigline}[1]{\item[{#1}]}
-\newcommand{\pysiglinewithargsret}[3]{%
- \settowidth{\py@argswidth}{#1\sphinxcode{(}}%
- \addtolength{\py@argswidth}{-2\py@argswidth}%
- \addtolength{\py@argswidth}{\linewidth}%
- \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}}]}
-\newcommand{\pysigstartmultiline}{%
- \def\pysigstartmultiline{\vskip\smallskipamount\parskip\z@skip\itemsep\z@skip}%
- \edef\pysigstopmultiline
- {\noexpand\leavevmode\parskip\the\parskip\relax\itemsep\the\itemsep\relax}%
- \parskip\z@skip\itemsep\z@skip
-}
-% Production lists
+%% STYLING
%
-\newenvironment{productionlist}{%
-% \def\sphinxoptional##1{{\Large[}##1{\Large]}}
- \def\production##1##2{\\\sphinxcode{\sphinxupquote{##1}}&::=&\sphinxcode{\sphinxupquote{##2}}}%
- \def\productioncont##1{\\& &\sphinxcode{\sphinxupquote{##1}}}%
- \parindent=2em
- \indent
- \setlength{\LTpre}{0pt}%
- \setlength{\LTpost}{0pt}%
- \begin{longtable}[l]{lcl}
-}{%
- \end{longtable}
-}
+\input{sphinxlatexstylepage.sty}
+\input{sphinxlatexstyleheadings.sty}
+\input{sphinxlatexstyletext.sty}
-% Definition lists; requested by AMK for HOWTO documents. Probably useful
-% elsewhere as well, so keep in in the general style support.
-%
-\newenvironment{definitions}{%
- \begin{description}%
- \def\term##1{\item[{##1}]\mbox{}\\*[0mm]}%
-}{%
- \end{description}%
-}
-%% FROM DOCTUTILS LATEX WRITER
-%
-% The following is stuff copied from docutils' latex writer.
+%% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
%
-\newcommand{\optionlistlabel}[1]{\normalfont\bfseries #1 \hfill}% \bf deprecated
-\newenvironment{optionlist}[1]
-{\begin{list}{}
- {\setlength{\labelwidth}{#1}
- \setlength{\rightmargin}{1cm}
- \setlength{\leftmargin}{\rightmargin}
- \addtolength{\leftmargin}{\labelwidth}
- \addtolength{\leftmargin}{\labelsep}
- \renewcommand{\makelabel}{\optionlistlabel}}
-}{\end{list}}
+\input{sphinxlatexobjects.sty}
-\newlength{\lineblockindentation}
-\setlength{\lineblockindentation}{2.5em}
-\newenvironment{lineblock}[1]
-{\begin{list}{}
- {\setlength{\partopsep}{\parskip}
- \addtolength{\partopsep}{\baselineskip}
- \topsep0pt\itemsep0.15\baselineskip\parsep0pt
- \leftmargin#1\relax}
- \raggedright}
-{\end{list}}
-% From docutils.writers.latex2e
-% inline markup (custom roles)
-% \DUrole{#1}{#2} tries \DUrole#1{#2}
-\providecommand*{\DUrole}[2]{%
- \ifcsname DUrole\detokenize{#1}\endcsname
- \csname DUrole\detokenize{#1}\endcsname{#2}%
- \else% backwards compatibility: try \docutilsrole#1{#2}
- \ifcsname docutilsrole\detokenize{#1}\endcsname
- \csname docutilsrole\detokenize{#1}\endcsname{#2}%
- \else
- #2%
- \fi
- \fi
-}
-
-\providecommand*{\DUprovidelength}[2]{%
- \ifdefined#1\else\newlength{#1}\setlength{#1}{#2}\fi
-}
-
-\DUprovidelength{\DUlineblockindent}{2.5em}
-\ifdefined\DUlineblock\else
- \newenvironment{DUlineblock}[1]{%
- \list{}{\setlength{\partopsep}{\parskip}
- \addtolength{\partopsep}{\baselineskip}
- \setlength{\topsep}{0pt}
- \setlength{\itemsep}{0.15\baselineskip}
- \setlength{\parsep}{0pt}
- \setlength{\leftmargin}{#1}}
- \raggedright
- }
- {\endlist}
-\fi
-
-%% TEXT STYLING
-%
-% to obtain straight quotes we execute \@noligs as patched by upquote, and
-% \scantokens is needed in cases where it would be too late for the macro to
-% first set catcodes and then fetch its argument. We also make the contents
-% breakable at non-escaped . , ; ? ! / using \sphinxbreaksviaactive,
-% and also at \ character (which is escaped to \textbackslash{}).
-\protected\def\sphinxtextbackslashbreakbefore
- {\discretionary{}{\sphinxafterbreak\sphinx@textbackslash}{\sphinx@textbackslash}}
-\protected\def\sphinxtextbackslashbreakafter
- {\discretionary{\sphinx@textbackslash}{\sphinxafterbreak}{\sphinx@textbackslash}}
-\let\sphinxtextbackslash\sphinxtextbackslashbreakafter
-% the macro must be protected if it ends up used in moving arguments,
-% in 'alltt' \@noligs is done already, and the \scantokens must be avoided.
-\protected\def\sphinxupquote#1{{\def\@tempa{alltt}%
- \ifx\@tempa\@currenvir\else
- \ifspx@opt@inlineliteralwraps
- % break at . , ; ? ! /
- \sphinxbreaksviaactive
- % break also at \
- \let\sphinx@textbackslash\textbackslash
- \let\textbackslash\sphinxtextbackslash
- % by default, no continuation symbol on next line but may be added
- \let\sphinxafterbreak\sphinxafterbreakofinlineliteral
- % do not overwrite the comma set-up
- \let\verbatim@nolig@list\sphinx@literal@nolig@list
- \fi
- % fix a space-gobbling issue due to LaTeX's original \do@noligs
-% TODO: using \@noligs as patched by upquote.sty is now unneeded because
-% either ` and ' are escaped (non-unicode engines) or they don't build
-% ligatures (unicode engines). Thus remove this and unify handling of `, <, >,
-% ' and - with the characters . , ; ? ! / as handled via
-% \sphinxbreaksviaactive.
-% Hence \sphinx@do@noligs will be removed, or rather replaced with code
-% inserting discretionaries, as they allow a continuation symbol on start of
-% next line to achieve common design with code-blocks.
- \let\do@noligs\sphinx@do@noligs
- \@noligs\endlinechar\m@ne\everyeof{}% (<- in case inside \sphinxhref)
- \expandafter\scantokens
- \fi {{#1}}}}% extra brace pair to fix end-space gobbling issue...
-\def\sphinx@do@noligs #1{\catcode`#1\active\begingroup\lccode`\~`#1\relax
- \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1 }}}
-\def\sphinx@literal@nolig@list {\do\`\do\<\do\>\do\'\do\-}%
-\let\sphinxafterbreakofinlineliteral\empty
-
-% Some custom font markup commands.
-\protected\def\sphinxstrong#1{\textbf{#1}}
-\protected\def\sphinxcode#1{\texttt{#1}}
-\protected\def\sphinxbfcode#1{\textbf{\sphinxcode{#1}}}
-\protected\def\sphinxemail#1{\textsf{#1}}
-\protected\def\sphinxtablecontinued#1{\textsf{#1}}
-\protected\def\sphinxtitleref#1{\emph{#1}}
-\protected\def\sphinxmenuselection#1{\emph{#1}}
-\protected\def\sphinxguilabel#1{\emph{#1}}
-\protected\def\sphinxkeyboard#1{\sphinxcode{#1}}
-\protected\def\sphinxaccelerator#1{\underline{#1}}
-\protected\def\sphinxcrossref#1{\emph{#1}}
-\protected\def\sphinxtermref#1{\emph{#1}}
-% \optional is used for ``[, arg]``, i.e. desc_optional nodes.
-\long\protected\def\sphinxoptional#1{%
- {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
-
-% additional customizable styling
-\def\sphinxstyleindexentry #1{\texttt{#1}}
-\def\sphinxstyleindexextra #1{ (\emph{#1})}
-\def\sphinxstyleindexpageref #1{, \pageref{#1}}
-\def\sphinxstyleindexpagemain#1{\textbf{#1}}
-\def\spxentry{\@backslashchar spxentry}% let to \sphinxstyleindexentry in index
-\def\spxextra{\@backslashchar spxextra}% let to \sphinxstyleindexextra in index
-\def\sphinxstyleindexlettergroup #1%
- {{\Large\sffamily#1}\nopagebreak\vspace{1mm}}
-\def\sphinxstyleindexlettergroupDefault #1%
- {{\Large\sffamily\sphinxnonalphabeticalgroupname}\nopagebreak\vspace{1mm}}
-\protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip}
-\let\sphinxstylesidebartitle\sphinxstyletopictitle
-\protected\def\sphinxstyleothertitle #1{\textbf{#1}}
-\protected\def\sphinxstylesidebarsubtitle #1{~\\\textbf{#1} \smallskip}
-% \text.. commands do not allow multiple paragraphs
-\protected\def\sphinxstyletheadfamily {\sffamily}
-\protected\def\sphinxstyleemphasis #1{\emph{#1}}
-\protected\def\sphinxstyleliteralemphasis#1{\emph{\sphinxcode{#1}}}
-\protected\def\sphinxstylestrong #1{\textbf{#1}}
-\protected\def\sphinxstyleliteralstrong#1{\sphinxbfcode{#1}}
-\protected\def\sphinxstyleabbreviation #1{\textsc{#1}}
-\protected\def\sphinxstyleliteralintitle#1{\sphinxcode{#1}}
-\newcommand*\sphinxstylecodecontinued[1]{\footnotesize(#1)}%
-\newcommand*\sphinxstylecodecontinues[1]{\footnotesize(#1)}%
-% figure legend comes after caption and may contain arbitrary body elements
-\newenvironment{sphinxlegend}{\par\small}{\par}
-% reduce hyperref "Token not allowed in a PDF string" warnings on PDF builds
-\AtBeginDocument{\pdfstringdefDisableCommands{%
-% all "protected" macros possibly ending up in section titles should be here
-% TODO: examine if \sphinxhref, \sphinxurl, \sphinnolinkurl should be handled
- \let\sphinxstyleemphasis \@firstofone
- \let\sphinxstyleliteralemphasis \@firstofone
- \let\sphinxstylestrong \@firstofone
- \let\sphinxstyleliteralstrong \@firstofone
- \let\sphinxstyleabbreviation \@firstofone
- \let\sphinxstyleliteralintitle \@firstofone
- \let\sphinxupquote \@firstofone
- \let\sphinxstrong \@firstofone
- \let\sphinxcode \@firstofone
- \let\sphinxbfcode \@firstofone
- \let\sphinxemail \@firstofone
- \let\sphinxcrossref \@firstofone
- \let\sphinxtermref \@firstofone
- \let\sphinxhyphen\sphinxhyphenforbookmarks
-}}
-
-% Special characters
-%
-% This definition prevents en-dash and em-dash TeX ligatures.
-%
-% It inserts a potential breakpoint after the hyphen. This is to keep in sync
-% with behavior in code-blocks, parsed and inline literals. For a breakpoint
-% before the hyphen use \leavevmode\kern\z@- (within \makeatletter/\makeatother)
-\protected\def\sphinxhyphen#1{-\kern\z@}
-% The {} from texescape mark-up is kept, else -- gives en-dash in PDF bookmark
-\def\sphinxhyphenforbookmarks{-}
-
-% For curly braces inside \index macro
-\def\sphinxleftcurlybrace{\{}
-\def\sphinxrightcurlybrace{\}}
+% FIXME: this line should be dropped, as "9" is default anyhow.
+\ifdefined\pdfcompresslevel\pdfcompresslevel = 9 \fi
-% Declare Unicode characters used by linux tree command to pdflatex utf8/utf8x
-\def\spx@bd#1#2{%
- \leavevmode
- \begingroup
- \ifx\spx@bd@height \@undefined\def\spx@bd@height{\baselineskip}\fi
- \ifx\spx@bd@width \@undefined\setbox0\hbox{0}\def\spx@bd@width{\wd0 }\fi
- \ifx\spx@bd@thickness\@undefined\def\spx@bd@thickness{.6\p@}\fi
- \ifx\spx@bd@lower \@undefined\def\spx@bd@lower{\dp\strutbox}\fi
- \lower\spx@bd@lower#1{#2}%
- \endgroup
-}%
-\@namedef{sphinx@u2500}% BOX DRAWINGS LIGHT HORIZONTAL
- {\spx@bd{\vbox to\spx@bd@height}
- {\vss\hrule\@height\spx@bd@thickness
- \@width\spx@bd@width\vss}}%
-\@namedef{sphinx@u2502}% BOX DRAWINGS LIGHT VERTICAL
- {\spx@bd{\hb@xt@\spx@bd@width}
- {\hss\vrule\@height\spx@bd@height
- \@width \spx@bd@thickness\hss}}%
-\@namedef{sphinx@u2514}% BOX DRAWINGS LIGHT UP AND RIGHT
- {\spx@bd{\hb@xt@\spx@bd@width}
- {\hss\raise.5\spx@bd@height
- \hb@xt@\z@{\hss\vrule\@height.5\spx@bd@height
- \@width \spx@bd@thickness\hss}%
- \vbox to\spx@bd@height{\vss\hrule\@height\spx@bd@thickness
- \@width.5\spx@bd@width\vss}}}%
-\@namedef{sphinx@u251C}% BOX DRAWINGS LIGHT VERTICAL AND RIGHT
- {\spx@bd{\hb@xt@\spx@bd@width}
- {\hss
- \hb@xt@\z@{\hss\vrule\@height\spx@bd@height
- \@width \spx@bd@thickness\hss}%
- \vbox to\spx@bd@height{\vss\hrule\@height\spx@bd@thickness
- \@width.5\spx@bd@width\vss}}}%
-\protected\def\sphinxunichar#1{\@nameuse{sphinx@u#1}}%
-% Tell TeX about pathological hyphenation cases:
-\hyphenation{Base-HTTP-Re-quest-Hand-ler}
\endinput
diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty
new file mode 100644
index 0000000000..1e418c8c22
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexadmonitions.sty
@@ -0,0 +1,148 @@
+%% NOTICES AND ADMONITIONS
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexadmonitions.sty}[2021/01/27 admonitions]
+
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - sphinxadmonition (environment)
+% This is a dispatch supporting
+%
+% - note, hint, important, tip (via sphinxlightbox)
+% - warning, caution, attention, danger, error (via sphinxheavybox)
+%
+% Each sphinx environment can be redefined by user.
+% The defaults are customizable via various colour and dimension
+% settings, cf sphinx docs (latex customization).
+%
+% Requires:
+\RequirePackage{framed}% used by sphinxheavybox
+%
+% Dependencies (they do not need to be defined at time of loading):
+% - of course the various colour and dimension options handled via sphinx.sty
+% - \sphinxstrong (for sphinxlightbox and sphinxheavybox)
+% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
+% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
+
+% Provides: (also in sphinxlatexliterals.sty)
+\providecommand*\sphinxvspacefixafterfrenchlists{%
+ \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
+}
+
+% Some are quite plain
+% the spx@notice@bordercolor etc are set in the sphinxadmonition environment
+\newenvironment{sphinxlightbox}{%
+ \par
+ \noindent{\color{spx@notice@bordercolor}%
+ \rule{\linewidth}{\spx@notice@border}}\par\nobreak
+ {\parskip\z@skip\noindent}%
+ }
+ {%
+ % counteract previous possible negative skip (French lists!):
+ % (we can't cancel that any earlier \vskip introduced a potential pagebreak)
+ \sphinxvspacefixafterfrenchlists
+ \nobreak\vbox{\noindent\kern\@totalleftmargin
+ {\color{spx@notice@bordercolor}%
+ \rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
+ {\linewidth}{\spx@notice@border}}\hss}\allowbreak
+ }% end of sphinxlightbox environment definition
+% may be renewenvironment'd by user for complete customization
+\newenvironment{sphinxnote}[1]
+ {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
+\newenvironment{sphinxhint}[1]
+ {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
+\newenvironment{sphinximportant}[1]
+ {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
+\newenvironment{sphinxtip}[1]
+ {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
+% or just use the package options
+% these are needed for common handling by notice environment of lightbox
+% and heavybox but they are currently not used by lightbox environment
+% and there is consequently no corresponding package option
+\definecolor{sphinxnoteBgColor}{rgb}{1,1,1}
+\definecolor{sphinxhintBgColor}{rgb}{1,1,1}
+\definecolor{sphinximportantBgColor}{rgb}{1,1,1}
+\definecolor{sphinxtipBgColor}{rgb}{1,1,1}
+
+% Others get more distinction
+% Code adapted from framed.sty's "snugshade" environment.
+% Nesting works (inner frames do not allow page breaks).
+\newenvironment{sphinxheavybox}{\par
+ \setlength{\FrameRule}{\spx@notice@border}%
+ \setlength{\FrameSep}{\dimexpr.6\baselineskip-\FrameRule\relax}
+ \advance\spx@image@maxheight
+ -\dimexpr2\FrameRule
+ +2\FrameSep
+ +\baselineskip\relax % will happen again if nested, needed indeed!
+ % configure framed.sty's parameters to obtain same vertical spacing
+ % as for "light" boxes. We need for this to manually insert parskip glue and
+ % revert a skip done by framed before the frame.
+ \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}%
+ \vspace{\FrameHeightAdjust}
+ % copied/adapted from framed.sty's snugshade
+ \def\FrameCommand##1{\hskip\@totalleftmargin
+ \fboxsep\FrameSep \fboxrule\FrameRule
+ \fcolorbox{spx@notice@bordercolor}{spx@notice@bgcolor}{##1}%
+ \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
+ \savenotes
+ % use a minipage if we are already inside a framed environment
+ \ifspx@inframed
+ \noindent\begin{minipage}{\linewidth}
+ \else
+ % handle case where notice is first thing in a list item (or is quoted)
+ \if@inlabel
+ \noindent\par\vspace{-\baselineskip}
+ \else
+ \vspace{\parskip}
+ \fi
+ \fi
+ \MakeFramed {\spx@inframedtrue
+ \advance\hsize-\width \@totalleftmargin\z@ \linewidth\hsize
+ % minipage initialization copied from LaTeX source code.
+ \@pboxswfalse
+ \let\@listdepth\@mplistdepth \@mplistdepth\z@
+ \@minipagerestore
+ \@setminipage }%
+ }
+ {%
+ \par\unskip
+ \@minipagefalse
+ \endMakeFramed
+ \ifspx@inframed\end{minipage}\fi
+ % set footnotes at bottom of page
+ \spewnotes
+ % arrange for similar spacing below frame as for "light" boxes.
+ \vskip .4\baselineskip
+ }% end of sphinxheavybox environment definition
+% may be renewenvironment'd by user for complete customization
+\newenvironment{sphinxwarning}[1]
+ {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+\newenvironment{sphinxcaution}[1]
+ {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+\newenvironment{sphinxattention}[1]
+ {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+\newenvironment{sphinxdanger}[1]
+ {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+\newenvironment{sphinxerror}[1]
+ {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+% or just use package options
+
+% the \colorlet of xcolor (if at all loaded) is overkill for our use case
+\newcommand{\sphinxcolorlet}[2]
+ {\expandafter\let\csname\@backslashchar color@#1\expandafter\endcsname
+ \csname\@backslashchar color@#2\endcsname }
+
+% the main dispatch for all types of notices
+\newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
+ % can't use #1 directly in definition of end part
+ \def\spx@noticetype {#1}%
+ % set parameters of heavybox/lightbox
+ \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
+ \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
+ \spx@notice@border \dimexpr\csname spx@opt@#1border\endcsname\relax
+ % start specific environment, passing the heading as argument
+ \begin{sphinx#1}{#2}}
+ % workaround some LaTeX "feature" of \end command
+ {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexgraphics.sty b/sphinx/texinputs/sphinxlatexgraphics.sty
new file mode 100644
index 0000000000..fd0aae6386
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexgraphics.sty
@@ -0,0 +1,122 @@
+%% GRAPHICS
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexgraphics.sty}[2021/01/27 graphics]
+
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - macros:
+%
+% - \sphinxfigcaption
+% - \sphinxincludegraphics
+%
+% - environments:
+%
+% - sphinxfigure-in-table
+%
+% May change:
+%
+% - \sphinxcaption (at begin document)
+%
+% Also provides:
+%
+% - \sphinxsafeincludegraphics (default of \sphinxincludegraphics since 2.0)
+% - \spx@image@maxheight dimension (used by sphinxlatexadmonitions.sty)
+% - \spx@image@box scratch box register (also used by sphinxlatexliterals.sty)
+%
+% Requires:
+% \RequirePackage{graphicx}% done in sphinx.sty
+\RequirePackage{amstext}% needed for \firstchoice@true(false)
+
+% \sphinxincludegraphics resizes images larger than the TeX \linewidth (which
+% is adjusted in indented environments), or taller than a certain maximal
+% height (usually \textheight and this is reduced in the environments which use
+% framed.sty to avoid infinite loop if image too tall).
+%
+% In case height or width options are present the rescaling is done
+% (since 2.0), in a way keeping the width:height ratio either native from
+% image or from the width and height options if both were present.
+%
+\newdimen\spx@image@maxheight
+\AtBeginDocument{\spx@image@maxheight\textheight}
+
+% box scratch register
+\newbox\spx@image@box
+\newcommand*{\sphinxsafeincludegraphics}[2][]{%
+ % #1 contains possibly width=, height=, but no scale= since 1.8.4
+ \setbox\spx@image@box\hbox{\includegraphics[#1,draft]{#2}}%
+ \in@false % use some handy boolean flag
+ \ifdim \wd\spx@image@box>\linewidth
+ \in@true % flag to remember to adjust options and set box dimensions
+ % compute height which results from rescaling width to \linewidth
+ % and keep current aspect ratio. multiply-divide in \numexpr uses
+ % temporarily doubled precision, hence no overflow. (of course we
+ % assume \ht is not a few sp's below \maxdimen...(about 16384pt).
+ \edef\spx@image@rescaledheight % with sp units
+ {\the\numexpr\ht\spx@image@box
+ *\linewidth/\wd\spx@image@box sp}%
+ \ifdim\spx@image@rescaledheight>\spx@image@maxheight
+ % the rescaled height will be too big, so it is height which decides
+ % the rescaling factor
+ \def\spx@image@requiredheight{\spx@image@maxheight}% dimen register
+ \edef\spx@image@requiredwidth % with sp units
+ {\the\numexpr\wd\spx@image@box
+ *\spx@image@maxheight/\ht\spx@image@box sp}%
+ % TODO: decide if this commented-out block could be needed due to
+ % rounding in numexpr operations going up
+ % \ifdim\spx@image@requiredwidth>\linewidth
+ % \def\spx@image@requiredwidth{\linewidth}% dimen register
+ % \fi
+ \else
+ \def\spx@image@requiredwidth{\linewidth}% dimen register
+ \let\spx@image@requiredheight\spx@image@rescaledheight% sp units
+ \fi
+ \else
+ % width is ok, let's check height
+ \ifdim\ht\spx@image@box>\spx@image@maxheight
+ \in@true
+ \edef\spx@image@requiredwidth % with sp units
+ {\the\numexpr\wd\spx@image@box
+ *\spx@image@maxheight/\ht\spx@image@box sp}%
+ \def\spx@image@requiredheight{\spx@image@maxheight}% dimen register
+ \fi
+ \fi % end of check of width and height
+ \ifin@
+ \setbox\spx@image@box
+ \hbox{\includegraphics
+ [%#1,% contained only width and/or height and overruled anyhow
+ width=\spx@image@requiredwidth,height=\spx@image@requiredheight]%
+ {#2}}%
+ % \includegraphics does not set box dimensions to the exactly
+ % requested ones, see https://github.com/latex3/latex2e/issues/112
+ \wd\spx@image@box\spx@image@requiredwidth
+ \ht\spx@image@box\spx@image@requiredheight
+ \leavevmode\box\spx@image@box
+ \else
+ % here we do not modify the options, no need to adjust width and height
+ % on output, they will be computed exactly as with "draft" option
+ \setbox\spx@image@box\box\voidb@x % clear memory
+ \includegraphics[#1]{#2}%
+ \fi
+}%
+% Use the "safe" one by default (2.0)
+\def\sphinxincludegraphics{\sphinxsafeincludegraphics}
+
+
+%% FIGURE IN TABLE
+%
+\newenvironment{sphinxfigure-in-table}[1][\linewidth]{%
+ \def\@captype{figure}%
+ \sphinxsetvskipsforfigintablecaption
+ \begin{minipage}{#1}%
+}{\end{minipage}}
+% tabulary expands twice contents, we need to prevent double counter stepping
+\newcommand*\sphinxfigcaption
+ {\ifx\equation$%$% this is trick to identify tabulary first pass
+ \firstchoice@false\else\firstchoice@true\fi
+ \spx@originalcaption }
+\newcommand*\sphinxsetvskipsforfigintablecaption
+ {\abovecaptionskip\smallskipamount
+ \belowcaptionskip\smallskipamount}
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexindbibtoc.sty b/sphinx/texinputs/sphinxlatexindbibtoc.sty
new file mode 100644
index 0000000000..79e30a1f19
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexindbibtoc.sty
@@ -0,0 +1,69 @@
+%% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexindbibtoc.sty}[2021/01/27 index, bib., toc]
+
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - environments: (backup defaults or get redefined)
+%
+% - sphinxtheindex (direct mark-up or via python.ist or sphinx.xdy)
+% - sphinxthebibliography
+%
+% - macros: (defines defaults)
+%
+% - \sphinxmaketitle
+% - \sphinxtableofcontents
+% - \sphinxnonalphabeticalgroupname
+% - \sphinxsymbolsname
+% - \sphinxnumbersname
+% - \sphinxcite
+%
+% Requires:
+\RequirePackage{makeidx}
+
+% fix the double index and bibliography on the table of contents
+% in jsclasses (Japanese standard document classes)
+\ifx\@jsc@uplatextrue\@undefined\else
+ \renewenvironment{sphinxtheindex}
+ {\cleardoublepage\phantomsection
+ \begin{theindex}}
+ {\end{theindex}}
+
+ \renewenvironment{sphinxthebibliography}[1]
+ {\cleardoublepage% \phantomsection % not needed here since TeXLive 2010's hyperref
+ \begin{thebibliography}{#1}}
+ {\end{thebibliography}}
+\fi
+
+% disable \@chappos in Appendix in pTeX
+\ifx\kanjiskip\@undefined\else
+ \let\py@OldAppendix=\appendix
+ \renewcommand{\appendix}{
+ \py@OldAppendix
+ \gdef\@chappos{}
+ }
+\fi
+
+% make commands known to non-Sphinx document classes
+\providecommand*{\sphinxmaketitle}{\maketitle}
+\providecommand*{\sphinxtableofcontents}{\tableofcontents}
+\ltx@ifundefined{sphinxthebibliography}
+ {\newenvironment
+ {sphinxthebibliography}{\begin{thebibliography}}{\end{thebibliography}}%
+ }
+ {}% else clause of \ltx@ifundefined
+\ltx@ifundefined{sphinxtheindex}
+ {\newenvironment{sphinxtheindex}{\begin{theindex}}{\end{theindex}}}%
+ {}% else clause of \ltx@ifundefined
+
+% for usage with xindy: this string gets internationalized in preamble
+\newcommand*{\sphinxnonalphabeticalgroupname}{}
+% redefined in preamble, headings for makeindex produced index
+\newcommand*{\sphinxsymbolsname}{}
+\newcommand*{\sphinxnumbersname}{}
+
+\protected\def\sphinxcite{\cite}
+
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexlists.sty b/sphinx/texinputs/sphinxlatexlists.sty
new file mode 100644
index 0000000000..3860090c29
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexlists.sty
@@ -0,0 +1,97 @@
+%% ALPHANUMERIC LIST ITEMS
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexlists.sty}[2021/01/27 lists]
+
+% Provides support for this output mark-up from Sphinx latex writer:
+% - \sphinxsetlistlabels
+
+% Dependencies: the \spx@opt@maxlistdepth from sphinx.sty
+
+\newcommand\sphinxsetlistlabels[5]
+{% #1 = style, #2 = enum, #3 = enumnext, #4 = prefix, #5 = suffix
+ % #2 and #3 are counters used by enumerate environement e.g. enumi, enumii.
+ % #1 is a macro such as \arabic or \alph
+ % prefix and suffix are strings (by default empty and a dot).
+ \@namedef{the#2}{#1{#2}}%
+ \@namedef{label#2}{#4\@nameuse{the#2}#5}%
+ \@namedef{p@#3}{\@nameuse{p@#2}#4\@nameuse{the#2}#5}%
+}%
+
+
+%% MAXLISTDEPTH
+%
+% remove LaTeX's cap on nesting depth if 'maxlistdepth' key used.
+% This is a hack, which works with the standard classes: it assumes \@toodeep
+% is always used in "true" branches: "\if ... \@toodeep \else .. \fi."
+
+% will force use the "false" branch (if there is one)
+\def\spx@toodeep@hack{\fi\iffalse}
+
+% do nothing if 'maxlistdepth' key not used or if package enumitem loaded.
+\ifnum\spx@opt@maxlistdepth=\z@\expandafter\@gobbletwo\fi
+\AtBeginDocument{%
+\@ifpackageloaded{enumitem}{\remove@to@nnil}{}%
+ \let\spx@toodeepORI\@toodeep
+ \def\@toodeep{%
+ \ifnum\@listdepth<\spx@opt@maxlistdepth\relax
+ \expandafter\spx@toodeep@hack
+ \else
+ \expandafter\spx@toodeepORI
+ \fi}%
+% define all missing \@list... macros
+ \count@\@ne
+ \loop
+ \ltx@ifundefined{@list\romannumeral\the\count@}
+ {\iffalse}{\iftrue\advance\count@\@ne}%
+ \repeat
+ \loop
+ \ifnum\count@>\spx@opt@maxlistdepth\relax\else
+ \expandafter\let
+ \csname @list\romannumeral\the\count@\expandafter\endcsname
+ \csname @list\romannumeral\the\numexpr\count@-\@ne\endcsname
+ % workaround 2.6--3.2d babel-french issue (fixed in 3.2e; no change needed)
+ \ltx@ifundefined{leftmargin\romannumeral\the\count@}
+ {\expandafter\let
+ \csname leftmargin\romannumeral\the\count@\expandafter\endcsname
+ \csname leftmargin\romannumeral\the\numexpr\count@-\@ne\endcsname}{}%
+ \advance\count@\@ne
+ \repeat
+% define all missing enum... counters and \labelenum... macros and \p@enum..
+ \count@\@ne
+ \loop
+ \ltx@ifundefined{c@enum\romannumeral\the\count@}
+ {\iffalse}{\iftrue\advance\count@\@ne}%
+ \repeat
+ \loop
+ \ifnum\count@>\spx@opt@maxlistdepth\relax\else
+ \newcounter{enum\romannumeral\the\count@}%
+ \expandafter\def
+ \csname labelenum\romannumeral\the\count@\expandafter\endcsname
+ \expandafter
+ {\csname theenum\romannumeral\the\numexpr\count@\endcsname.}%
+ \expandafter\def
+ \csname p@enum\romannumeral\the\count@\expandafter\endcsname
+ \expandafter
+ {\csname p@enum\romannumeral\the\numexpr\count@-\@ne\expandafter
+ \endcsname\csname theenum\romannumeral\the\numexpr\count@-\@ne\endcsname.}%
+ \advance\count@\@ne
+ \repeat
+% define all missing labelitem... macros
+ \count@\@ne
+ \loop
+ \ltx@ifundefined{labelitem\romannumeral\the\count@}
+ {\iffalse}{\iftrue\advance\count@\@ne}%
+ \repeat
+ \loop
+ \ifnum\count@>\spx@opt@maxlistdepth\relax\else
+ \expandafter\let
+ \csname labelitem\romannumeral\the\count@\expandafter\endcsname
+ \csname labelitem\romannumeral\the\numexpr\count@-\@ne\endcsname
+ \advance\count@\@ne
+ \repeat
+ \PackageInfo{sphinx}{maximal list depth extended to \spx@opt@maxlistdepth}%
+\@gobble\@nnil
+}
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexliterals.sty b/sphinx/texinputs/sphinxlatexliterals.sty
new file mode 100644
index 0000000000..a2943b2dc2
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexliterals.sty
@@ -0,0 +1,774 @@
+%% LITERAL BLOCKS
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexliterals.sty}[2021/01/27 code-blocks and parsed literals]
+
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - macros:
+% - \sphinxLiteralBlockLabel
+% - \sphinxSetupCaptionForVerbatim
+% - \sphinxSetupCodeBlockInFootnote
+% - \sphinxhref
+% - \sphinxnolinkurl
+% - \sphinxresetverbatimhllines
+% - \sphinxunactivateextrasandspace
+% - \sphinxupquote
+% - \sphinxurl
+%
+% - environments:
+% - sphinxVerbatim
+% - sphinxVerbatimintable
+% - sphinxalltt
+%
+% Dependency:
+%
+% - hyperref (for \phantomsection and \capstart) (loaded later)
+%
+% Executes \RequirePackage for:
+%
+% - framed
+% - fancyvrb
+% - alltt
+% - upquote
+% - needspace
+
+% also in sphinxlatexadmonitions.sty:
+% This is a workaround to a "feature" of French lists, when literal block
+% follows immediately; usable generally (does only \par then), a priori...
+\providecommand*\sphinxvspacefixafterfrenchlists{%
+ \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
+}
+
+% For framing allowing pagebreaks
+\RequirePackage{framed}
+% For source code
+% MEMO: fancyvrb is used mainly to
+% 1- control horizontal and vertical spacing
+% 2- optional line numbering
+% 3- optional line emphasizing
+% 4- while still allowing expansion of Pygments latex mark-up
+% Other aspects such as framing, caption handling, codeline wrapping are
+% added on top of it. We should stop using fancyvrb and implement
+% 1, 2, 3, 4 by own Sphinx fully native Verbatim. This would allow to solve
+% limitations with wrapped long code line not allowing page break.
+\RequirePackage{fancyvrb}
+% For parsed-literal blocks.
+\RequirePackage{alltt}
+% Display "real" single quotes in literal blocks.
+\RequirePackage{upquote}
+% Skip to next page if not enough space at bottom
+\RequirePackage{needspace}
+
+% Based on use of "fancyvrb.sty"'s Verbatim.
+% - with framing allowing page breaks ("framed.sty")
+% - with breaking of long lines (exploits Pygments mark-up),
+% - with possibly of a top caption, non-separable by pagebreak.
+% - and usable inside tables or footnotes ("sphinxpackagefootnote.sty").
+
+% for emphasizing lines
+\define@key{FV}{hllines}{\def\sphinx@verbatim@checkifhl##1{\in@{, ##1,}{#1}}}
+% sphinxVerbatim must be usable by third party without requiring hllines set-up
+\def\sphinxresetverbatimhllines{\def\sphinx@verbatim@checkifhl##1{\in@false}}
+\sphinxresetverbatimhllines
+
+% Prior to Sphinx 1.5, \Verbatim and \endVerbatim were modified by Sphinx.
+% The aliases defined here are used in sphinxVerbatim environment and can
+% serve as hook-points with no need to modify \Verbatim itself.
+\let\OriginalVerbatim \Verbatim
+\let\endOriginalVerbatim\endVerbatim
+
+% for captions of literal blocks
+% at start of caption title
+\newcommand*{\fnum@literalblock}{\literalblockname\nobreakspace\theliteralblock}
+% this will be overwritten in document preamble by Babel translation
+\newcommand*{\literalblockname}{Listing }
+% file extension needed for \caption's good functioning, the file is created
+% only if a \listof{literalblock}{foo} command is encountered, which is
+% analogous to \listoffigures, but for the code listings (foo = chosen title.)
+\newcommand*{\ext@literalblock}{lol}
+
+% if forced use of minipage encapsulation is needed (e.g. table cells)
+\newif\ifsphinxverbatimwithminipage \sphinxverbatimwithminipagefalse
+
+% Framing macro for use with framed.sty's \FrameCommand
+% - it obeys current indentation,
+% - frame is \fboxsep separated from the contents,
+% - the contents use the full available text width,
+% - #1 = color of frame, #2 = color of background,
+% - #3 = above frame, #4 = below frame, #5 = within frame,
+% - #3 and #4 must be already typeset boxes; they must issue \normalcolor
+% or similar, else, they are under scope of color #1
+\long\def\spx@fcolorbox #1#2#3#4#5{%
+ \hskip\@totalleftmargin
+ \hskip-\fboxsep\hskip-\fboxrule
+ % use of \color@b@x here is compatible with both xcolor.sty and color.sty
+ \color@b@x {\color{#1}\spx@CustomFBox{#3}{#4}}{\color{#2}}{#5}%
+ \hskip-\fboxsep\hskip-\fboxrule
+ \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth
+}%
+% #1 = for material above frame, such as a caption or a "continued" hint
+% #2 = for material below frame, such as a caption or "continues on next page"
+% #3 = actual contents, which will be typeset with a background color
+\long\def\spx@CustomFBox#1#2#3{%
+ \begingroup
+ \setbox\@tempboxa\hbox{{#3}}% inner braces to avoid color leaks
+ \vbox{#1% above frame
+ % draw frame border _latest_ to avoid pdf viewer issue
+ \kern\fboxrule
+ \hbox{\kern\fboxrule
+ \copy\@tempboxa
+ \kern-\wd\@tempboxa\kern-\fboxrule
+ \vrule\@width\fboxrule
+ \kern\wd\@tempboxa
+ \vrule\@width\fboxrule}%
+ \kern-\dimexpr\ht\@tempboxa+\dp\@tempboxa+\fboxrule\relax
+ \hrule\@height\fboxrule
+ \kern\dimexpr\ht\@tempboxa+\dp\@tempboxa\relax
+ \hrule\@height\fboxrule
+ #2% below frame
+ }%
+ \endgroup
+}%
+\def\spx@fcolorbox@put@c#1{% hide width from framed.sty measuring
+ \moveright\dimexpr\fboxrule+.5\wd\@tempboxa\hb@xt@\z@{\hss#1\hss}%
+}%
+\def\spx@fcolorbox@put@r#1{% right align with contents, width hidden
+ \moveright\dimexpr\fboxrule+\wd\@tempboxa-\fboxsep\hb@xt@\z@{\hss#1}%
+}%
+\def\spx@fcolorbox@put@l#1{% left align with contents, width hidden
+ \moveright\dimexpr\fboxrule+\fboxsep\hb@xt@\z@{#1\hss}%
+}%
+%
+\def\sphinxVerbatim@Continued
+ {\csname spx@fcolorbox@put@\spx@opt@verbatimcontinuedalign\endcsname
+ {\normalcolor\sphinxstylecodecontinued\literalblockcontinuedname}}%
+\def\sphinxVerbatim@Continues
+ {\csname spx@fcolorbox@put@\spx@opt@verbatimcontinuesalign\endcsname
+ {\normalcolor\sphinxstylecodecontinues\literalblockcontinuesname}}%
+\def\sphinxVerbatim@Title
+ {\spx@fcolorbox@put@c{\unhcopy\sphinxVerbatim@TitleBox}}%
+\let\sphinxVerbatim@Before\@empty
+\let\sphinxVerbatim@After\@empty
+% Defaults are redefined in document preamble according to language
+\newcommand*\literalblockcontinuedname{continued from previous page}%
+\newcommand*\literalblockcontinuesname{continues on next page}%
+%
+\def\spx@verbatimfcolorbox{\spx@fcolorbox{VerbatimBorderColor}{VerbatimColor}}%
+\def\sphinxVerbatim@FrameCommand
+ {\spx@verbatimfcolorbox\sphinxVerbatim@Before\sphinxVerbatim@After}%
+\def\sphinxVerbatim@FirstFrameCommand
+ {\spx@verbatimfcolorbox\sphinxVerbatim@Before\sphinxVerbatim@Continues}%
+\def\sphinxVerbatim@MidFrameCommand
+ {\spx@verbatimfcolorbox\sphinxVerbatim@Continued\sphinxVerbatim@Continues}%
+\def\sphinxVerbatim@LastFrameCommand
+ {\spx@verbatimfcolorbox\sphinxVerbatim@Continued\sphinxVerbatim@After}%
+
+% For linebreaks inside Verbatim environment from package fancyvrb.
+\newbox\sphinxcontinuationbox
+\newbox\sphinxvisiblespacebox
+\newcommand*\sphinxafterbreak {\copy\sphinxcontinuationbox}
+
+% Take advantage of the already applied Pygments mark-up to insert
+% potential linebreaks for TeX processing.
+% {, <, #, %, $, ' and ": go to next line.
+% _, }, ^, &, >, -, ~, and \: stay at end of broken line.
+% Use of \textquotesingle for straight quote.
+% FIXME: convert this to package options ?
+\newcommand*\sphinxbreaksbeforelist {%
+ \do\PYGZob\{\do\PYGZlt\<\do\PYGZsh\#\do\PYGZpc\%% {, <, #, %,
+ \do\PYGZdl\$\do\PYGZdq\"% $, "
+ \def\PYGZsq
+ {\discretionary{}{\sphinxafterbreak\textquotesingle}{\textquotesingle}}% '
+}
+\newcommand*\sphinxbreaksafterlist {%
+ \do\PYGZus\_\do\PYGZcb\}\do\PYGZca\^\do\PYGZam\&% _, }, ^, &,
+ \do\PYGZgt\>\do\PYGZhy\-\do\PYGZti\~% >, -, ~
+ \do\PYGZbs\\% \
+}
+\newcommand*\sphinxbreaksatspecials {%
+ \def\do##1##2%
+ {\def##1{\discretionary{}{\sphinxafterbreak\char`##2}{\char`##2}}}%
+ \sphinxbreaksbeforelist
+ \def\do##1##2%
+ {\def##1{\discretionary{\char`##2}{\sphinxafterbreak}{\char`##2}}}%
+ \sphinxbreaksafterlist
+}
+
+\def\sphinx@verbatim@nolig@list {\do \`}%
+% Some characters . , ; ? ! / are neither pygmentized nor "tex-escaped".
+% This macro makes them "active" and they will insert potential linebreaks.
+% Not compatible with math mode (cf \sphinxunactivateextras).
+\newcommand*\sphinxbreaksbeforeactivelist {}% none
+\newcommand*\sphinxbreaksafteractivelist {\do\.\do\,\do\;\do\?\do\!\do\/}
+\newcommand*\sphinxbreaksviaactive {%
+ \def\do##1{\lccode`\~`##1%
+ \lowercase{\def~}{\discretionary{}{\sphinxafterbreak\char`##1}{\char`##1}}%
+ \catcode`##1\active}%
+ \sphinxbreaksbeforeactivelist
+ \def\do##1{\lccode`\~`##1%
+ \lowercase{\def~}{\discretionary{\char`##1}{\sphinxafterbreak}{\char`##1}}%
+ \catcode`##1\active}%
+ \sphinxbreaksafteractivelist
+ \lccode`\~`\~
+}
+
+% If the linebreak is at a space, the latter will be displayed as visible
+% space at end of first line, and a continuation symbol starts next line.
+\def\spx@verbatim@space {%
+ \nobreak\hskip\z@skip
+ \discretionary{\copy\sphinxvisiblespacebox}{\sphinxafterbreak}
+ {\kern\fontdimen2\font}%
+}%
+
+% if the available space on page is less than \literalblockneedspace, insert pagebreak
+\newcommand{\sphinxliteralblockneedspace}{5\baselineskip}
+\newcommand{\sphinxliteralblockwithoutcaptionneedspace}{1.5\baselineskip}
+% The title (caption) is specified from outside as macro \sphinxVerbatimTitle.
+% \sphinxVerbatimTitle is reset to empty after each use of Verbatim.
+\newcommand*\sphinxVerbatimTitle {}
+% This box to typeset the caption before framed.sty multiple passes for framing.
+\newbox\sphinxVerbatim@TitleBox
+% This box to measure contents if nested as inner \MakeFramed requires then
+% minipage encapsulation but too long contents then break outer \MakeFramed
+\newbox\sphinxVerbatim@ContentsBox
+% Holder macro for labels of literal blocks. Set-up by LaTeX writer.
+\newcommand*\sphinxLiteralBlockLabel {}
+\newcommand*\sphinxSetupCaptionForVerbatim [1]
+{%
+ \sphinxvspacefixafterfrenchlists
+ \needspace{\sphinxliteralblockneedspace}%
+% insert a \label via \sphinxLiteralBlockLabel
+% reset to normal the color for the literal block caption
+ \def\sphinxVerbatimTitle
+ {\py@NormalColor\sphinxcaption{\sphinxLiteralBlockLabel #1}}%
+}
+\newcommand*\sphinxSetupCodeBlockInFootnote {%
+ \fvset{fontsize=\footnotesize}\let\caption\sphinxfigcaption
+ \sphinxverbatimwithminipagetrue % reduces vertical spaces
+ % we counteract (this is in a group) the \@normalsize from \caption
+ \let\normalsize\footnotesize\let\@parboxrestore\relax
+ \def\spx@abovecaptionskip{\sphinxverbatimsmallskipamount}%
+}
+\newcommand*{\sphinxverbatimsmallskipamount}{\smallskipamount}
+% serves to implement line highlighting and line wrapping
+\newcommand\sphinxFancyVerbFormatLine[1]{%
+ \expandafter\sphinx@verbatim@checkifhl\expandafter{\the\FV@CodeLineNo}%
+ \ifin@
+ \sphinxVerbatimHighlightLine{#1}%
+ \else
+ \sphinxVerbatimFormatLine{#1}%
+ \fi
+}%
+\newcommand\sphinxVerbatimHighlightLine[1]{%
+ \edef\sphinxrestorefboxsep{\fboxsep\the\fboxsep\relax}%
+ \fboxsep0pt\relax % cf LaTeX bug graphics/4524
+ \colorbox{sphinxVerbatimHighlightColor}%
+ {\sphinxrestorefboxsep\sphinxVerbatimFormatLine{#1}}%
+ % no need to restore \fboxsep here, as this ends up in a \hbox from fancyvrb
+}%
+% \sphinxVerbatimFormatLine will be set locally to one of those two:
+\newcommand\sphinxVerbatimFormatLineWrap{%
+ \hsize\linewidth
+ \ifspx@opt@verbatimforcewraps
+ \expandafter\spx@verb@FormatLineForceWrap
+ \else\expandafter\spx@verb@FormatLineWrap
+ \fi
+}%
+\newcommand\sphinxVerbatimFormatLineNoWrap[1]{\hb@xt@\linewidth{\strut #1\hss}}%
+\long\def\spx@verb@FormatLineWrap#1{%
+ \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
+ \doublehyphendemerits\z@\finalhyphendemerits\z@
+ \strut #1\strut}%
+}%
+%
+% The normal line wrapping allows breaks at spaces and ascii non
+% letters, non digits. The \raggedright above means there will be
+% an overfilled line only if some non-breakable "word" was
+% encountered, which is longer than a line (it is moved always to
+% be on its own on a new line).
+%
+% The "forced" line wrapping will parse the tokens to add potential
+% breakpoints at each character. As some strings are highlighted,
+% we have to apply the highlighting character per character, which
+% requires to manipulate the output of the Pygments LaTeXFormatter.
+%
+% Doing this at latex level is complicated. The contents should
+% be as expected: i.e. some active characters from
+% \sphinxbreaksviaactive, some Pygments character escapes such as
+% \PYGZdl{}, and the highlighting \PYG macro with always 2
+% arguments. No other macros should be there, except perhaps
+% zero-parameter macros. In particular:
+% - the texcomments Pygments option must be set to False
+%
+% With pdflatex, Unicode input gives multi-bytes characters
+% where the first byte is active. We support the "utf8" macros
+% only. "utf8x" is not supported.
+%
+% The highlighting macro \PYG will be applied character per
+% character. Highlighting via a colored background gives thus a
+% chain of small colored boxes which may cause some artefact in
+% some pdf viewers. Can't do anything here if we do want the line
+% break to be possible.
+%
+% First a measurement step is done of what would the standard line
+% wrapping give (i.e line breaks only at spaces and non-letter,
+% non-digit ascii characters), cf TeX by Topic for the basic
+% dissecting technique: TeX unfortunately when building a vertical
+% box does not store in an accessible way what was the maximal
+% line-width during paragraph building.
+%
+% If the max width exceeds the linewidth by more than verbatimmaxoverfull
+% character widths, or if the min width plus verbatimmaxunderfull character
+% widths is inferior to linewidth, then we apply the "force wrapping" with
+% potential line break at each character, else we don't.
+\long\def\spx@verb@FormatLineForceWrap#1{%
+ % \spx@image@box is a scratch box register that we can use here
+ \global\let\spx@verb@maxwidth\z@
+ \global\let\spx@verb@minwidth\linewidth
+ \setbox\spx@image@box
+ \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
+ \doublehyphendemerits\z@\finalhyphendemerits\z@
+ \strut #1\strut\@@par
+ \spx@verb@getwidths}%
+ \ifdim\spx@verb@maxwidth>
+ \dimexpr\linewidth+\spx@opt@verbatimmaxoverfull\fontcharwd\font`X \relax
+ \spx@verb@FormatLineWrap{\spx@verb@wrapPYG #1\spx@verb@wrapPYG}%
+ \else
+ \ifdim\spx@verb@minwidth<
+ \dimexpr\linewidth-\spx@opt@verbatimmaxunderfull\fontcharwd\font`X \relax
+ \spx@verb@FormatLineWrap{\spx@verb@wrapPYG #1\spx@verb@wrapPYG}%
+ \else
+ \spx@verb@FormatLineWrap{#1}%
+ \fi\fi
+}%
+% auxiliary paragraph dissector to get max and min widths
+% but minwidth must not take into account the last line
+\newbox\spx@scratchbox
+\def\spx@verb@getwidths {%
+ \unskip\unpenalty
+ \setbox\spx@scratchbox\lastbox
+ \ifvoid\spx@scratchbox
+ \else
+ \setbox\spx@scratchbox\hbox{\unhbox\spx@scratchbox}%
+ \ifdim\spx@verb@maxwidth<\wd\spx@scratchbox
+ \xdef\spx@verb@maxwidth{\number\wd\spx@scratchbox sp}%
+ \fi
+ \expandafter\spx@verb@getwidths@loop
+ \fi
+}%
+\def\spx@verb@getwidths@loop {%
+ \unskip\unpenalty
+ \setbox\spx@scratchbox\lastbox
+ \ifvoid\spx@scratchbox
+ \else
+ \setbox\spx@scratchbox\hbox{\unhbox\spx@scratchbox}%
+ \ifdim\spx@verb@maxwidth<\wd\spx@scratchbox
+ \xdef\spx@verb@maxwidth{\number\wd\spx@scratchbox sp}%
+ \fi
+ \ifdim\spx@verb@minwidth>\wd\spx@scratchbox
+ \xdef\spx@verb@minwidth{\number\wd\spx@scratchbox sp}%
+ \fi
+ \expandafter\spx@verb@getwidths@loop
+ \fi
+}%
+% auxiliary macros to implement "cut long line even in middle of word"
+\catcode`Z=3 % safe delimiter
+\def\spx@verb@wrapPYG{%
+ \futurelet\spx@nexttoken\spx@verb@wrapPYG@i
+}%
+\def\spx@verb@wrapPYG@i{%
+ \ifx\spx@nexttoken\spx@verb@wrapPYG\let\next=\@gobble\else
+ \ifx\spx@nexttoken\PYG\let\next=\spx@verb@wrapPYG@PYG@onebyone\else
+ \discretionary{}{\sphinxafterbreak}{}%
+ \let\next\spx@verb@wrapPYG@ii
+ \fi\fi
+ \next
+}%
+% Let's recognize active characters. We don't support utf8x only utf8.
+% And here #1 should not have picked up (non empty) braced contents
+\long\def\spx@verb@wrapPYG@ii#1{%
+ \ifcat\noexpand~\noexpand#1\relax% active character
+ \expandafter\spx@verb@wrapPYG@active
+ \else % non-active character, control sequence such as \PYGZdl, or empty
+ \expandafter\spx@verb@wrapPYG@one
+ \fi {#1}%
+}%
+\long\def\spx@verb@wrapPYG@active#1{%
+% Let's hope expansion of active character does not really require arguments,
+% as we certainly don't want to go into expanding upfront token stream anyway.
+ \expandafter\spx@verb@wrapPYG@iii#1{}{}{}{}{}{}{}{}{}Z#1%
+}%
+\long\def\spx@verb@wrapPYG@iii#1#2Z{%
+ \ifx\UTFviii@four@octets#1\let\next=\spx@verb@wrapPYG@four\else
+ \ifx\UTFviii@three@octets#1\let\next=\spx@verb@wrapPYG@three\else
+ \ifx\UTFviii@two@octets#1\let\next=\spx@verb@wrapPYG@two\else
+ \let\next=\spx@verb@wrapPYG@one
+ \fi\fi\fi
+ \next
+}%
+\long\def\spx@verb@wrapPYG@one #1{#1\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
+\long\def\spx@verb@wrapPYG@two #1#2{#1#2\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
+\long\def\spx@verb@wrapPYG@three #1#2#3{#1#2#3\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
+\long\def\spx@verb@wrapPYG@four #1#2#3#4{#1#2#3#4\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
+% Replace \PYG by itself applied one character at a time! This way breakpoints
+% can be inserted.
+\def\spx@verb@wrapPYG@PYG@onebyone#1#2#3{% #1 = \PYG, #2 = highlight spec, #3 = tokens
+ \def\spx@verb@wrapPYG@PYG@spec{{#2}}%
+ \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i#3Z%
+}%
+\def\spx@verb@wrapPYG@PYG@i{%
+ \ifx\spx@nexttokenZ\let\next=\spx@verb@wrapPYG@PYG@done\else
+ \discretionary{}{\sphinxafterbreak}{}%
+ \let\next\spx@verb@wrapPYG@PYG@ii
+ \fi
+ \next
+}%
+\def\spx@verb@wrapPYG@PYG@doneZ{\futurelet\spx@nexttoken\spx@verb@wrapPYG@i}%
+\long\def\spx@verb@wrapPYG@PYG@ii#1{%
+ \ifcat\noexpand~\noexpand#1\relax% active character
+ \expandafter\spx@verb@wrapPYG@PYG@active
+ \else % non-active character, control sequence such as \PYGZdl, or empty
+ \expandafter\spx@verb@wrapPYG@PYG@one
+ \fi {#1}%
+}%
+\long\def\spx@verb@wrapPYG@PYG@active#1{%
+% Let's hope expansion of active character does not really require arguments,
+% as we certainly don't want to go into expanding upfront token stream anyway.
+ \expandafter\spx@verb@wrapPYG@PYG@iii#1{}{}{}{}{}{}{}{}{}Z#1%
+}%
+\long\def\spx@verb@wrapPYG@PYG@iii#1#2Z{%
+ \ifx\UTFviii@four@octets#1\let\next=\spx@verb@wrapPYG@PYG@four\else
+ \ifx\UTFviii@three@octets#1\let\next=\spx@verb@wrapPYG@PYG@three\else
+ \ifx\UTFviii@two@octets#1\let\next=\spx@verb@wrapPYG@PYG@two\else
+ \let\next=\spx@verb@wrapPYG@PYG@one
+ \fi\fi\fi
+ \next
+}%
+\long\def\spx@verb@wrapPYG@PYG@one#1{%
+ \expandafter\PYG\spx@verb@wrapPYG@PYG@spec{#1}%
+ \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i
+}%
+\long\def\spx@verb@wrapPYG@PYG@two#1#2{%
+ \expandafter\PYG\spx@verb@wrapPYG@PYG@spec{#1#2}%
+ \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i
+}%
+\long\def\spx@verb@wrapPYG@PYG@three#1#2#3{%
+ \expandafter\PYG\spx@verb@wrapPYG@PYG@spec{#1#2#3}%
+ \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i
+}%
+\long\def\spx@verb@wrapPYG@PYG@four#1#2#3#4{%
+ \expandafter\PYG\spx@verb@wrapPYG@PYG@spec{#1#2#3#4}%
+ \futurelet\spx@nexttoken\spx@verb@wrapPYG@PYG@i
+}%
+\catcode`Z 11 %
+%
+\g@addto@macro\FV@SetupFont{%
+ \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
+ \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
+}%
+\newenvironment{sphinxVerbatim}{%
+ % first, let's check if there is a caption
+ \ifx\sphinxVerbatimTitle\empty
+ \sphinxvspacefixafterfrenchlists
+ \parskip\z@skip
+ \vskip\sphinxverbatimsmallskipamount
+ % there was no caption. Check if nevertheless a label was set.
+ \ifx\sphinxLiteralBlockLabel\empty\else
+ % we require some space to be sure hyperlink target from \phantomsection
+ % will not be separated from upcoming verbatim by a page break
+ \needspace{\sphinxliteralblockwithoutcaptionneedspace}%
+ \phantomsection\sphinxLiteralBlockLabel
+ \fi
+ \else
+ \parskip\z@skip
+ \if t\spx@opt@literalblockcappos
+ \vskip\spx@abovecaptionskip
+ \def\sphinxVerbatim@Before
+ {\sphinxVerbatim@Title\nointerlineskip
+ \kern\dimexpr-\dp\strutbox+\sphinxbelowcaptionspace
+ % if no frame (code-blocks inside table cells), remove
+ % the "verbatimsep" whitespace from the top (better visually)
+ \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi
+ % caption package adds \abovecaptionskip vspace, remove it
+ \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax}%
+ \else
+ \vskip\sphinxverbatimsmallskipamount
+ \def\sphinxVerbatim@After
+ {\nointerlineskip\kern\dimexpr\dp\strutbox
+ \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi
+ \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax
+ \sphinxVerbatim@Title}%
+ \fi
+ \def\@captype{literalblock}%
+ \capstart
+ % \sphinxVerbatimTitle must reset color
+ \setbox\sphinxVerbatim@TitleBox
+ \hbox{\begin{minipage}{\linewidth}%
+ % caption package may detect wrongly if top or bottom, so we help it
+ \spx@ifcaptionpackage
+ {\caption@setposition{\spx@opt@literalblockcappos}}{}%
+ \sphinxVerbatimTitle
+ \end{minipage}}%
+ \fi
+ \global\let\sphinxLiteralBlockLabel\empty
+ \global\let\sphinxVerbatimTitle\empty
+ \fboxsep\sphinxverbatimsep \fboxrule\sphinxverbatimborder
+ \ifspx@opt@verbatimwithframe\else\fboxrule\z@\fi
+ \let\FrameCommand \sphinxVerbatim@FrameCommand
+ \let\FirstFrameCommand\sphinxVerbatim@FirstFrameCommand
+ \let\MidFrameCommand \sphinxVerbatim@MidFrameCommand
+ \let\LastFrameCommand \sphinxVerbatim@LastFrameCommand
+ \ifspx@opt@verbatimhintsturnover\else
+ \let\sphinxVerbatim@Continued\@empty
+ \let\sphinxVerbatim@Continues\@empty
+ \fi
+ \ifspx@opt@verbatimwrapslines
+ % fancyvrb's Verbatim puts each input line in (unbreakable) horizontal boxes.
+ % This customization wraps each line from the input in a \vtop, thus
+ % allowing it to wrap and display on two or more lines in the latex output.
+ % - The codeline counter will be increased only once.
+ % - The wrapped material will not break across pages, it is impossible
+ % to achieve this without extensive rewrite of fancyvrb.
+ % - The (not used in sphinx) obeytabs option to Verbatim is
+ % broken by this change (showtabs and tabspace work).
+ \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineWrap
+ \let\FV@Space\spx@verbatim@space
+ % Allow breaks at special characters using \PYG... macros.
+ \sphinxbreaksatspecials
+ % Breaks at punctuation characters . , ; ? ! and / (needs catcode activation)
+ \fvset{codes*=\sphinxbreaksviaactive}%
+ \else % end of conditional code for wrapping long code lines
+ \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineNoWrap
+ \fi
+ \let\FancyVerbFormatLine\sphinxFancyVerbFormatLine
+ \VerbatimEnvironment
+ % workaround to fancyvrb's check of current list depth
+ \def\@toodeep {\advance\@listdepth\@ne}%
+ % The list environment is needed to control perfectly the vertical space.
+ % Note: \OuterFrameSep used by framed.sty is later set to \topsep hence 0pt.
+ % - if caption: distance from last text baseline to caption baseline is
+ % A+(B-F)+\ht\strutbox, A = \abovecaptionskip (default 10pt), B =
+ % \baselineskip, F is the framed.sty \FrameHeightAdjust macro, default 6pt.
+ % Formula valid for F < 10pt.
+ % - distance of baseline of caption to top of frame is like for tables:
+ % \sphinxbelowcaptionspace (=0.5\baselineskip)
+ % - if no caption: distance of last text baseline to code frame is S+(B-F),
+ % with S = \sphinxverbatimtopskip (=\smallskip)
+ % - and distance from bottom of frame to next text baseline is
+ % \baselineskip+\parskip.
+ % The \trivlist is used to avoid possible "too deeply nested" error.
+ \itemsep \z@skip
+ \topsep \z@skip
+ \partopsep \z@skip
+ % trivlist will set \parsep to \parskip (which itself is set to zero above)
+ % \leftmargin will be set to zero by trivlist
+ \rightmargin\z@
+ \parindent \z@% becomes \itemindent. Default zero, but perhaps overwritten.
+ \trivlist\item\relax
+ \ifspx@inframed\setbox\sphinxVerbatim@ContentsBox\vbox\bgroup
+ \@setminipage\hsize\linewidth
+ % use bulk of minipage paragraph shape restores (this is needed
+ % in indented contexts, at least for some)
+ \textwidth\hsize \columnwidth\hsize \@totalleftmargin\z@
+ \leftskip\z@skip \rightskip\z@skip \@rightskip\z@skip
+ \else
+ \ifsphinxverbatimwithminipage\noindent\begin{minipage}{\linewidth}\fi
+ \MakeFramed {% adapted over from framed.sty's snugshade environment
+ \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage
+ }%
+ \fi
+ % For grid placement from \strut's in \FancyVerbFormatLine
+ \lineskip\z@skip
+ % active comma should not be overwritten by \@noligs
+ \ifspx@opt@verbatimwrapslines
+ \let\verbatim@nolig@list \sphinx@verbatim@nolig@list
+ \fi
+ % will fetch its optional arguments if any
+ \OriginalVerbatim
+}
+{%
+ \endOriginalVerbatim
+ \ifspx@inframed
+ \egroup % finish \sphinxVerbatim@ContentsBox vbox
+ \nobreak % update page totals
+ \ifdim\dimexpr\ht\sphinxVerbatim@ContentsBox+
+ \dp\sphinxVerbatim@ContentsBox+
+ \ht\sphinxVerbatim@TitleBox+
+ \dp\sphinxVerbatim@TitleBox+
+ 2\fboxsep+2\fboxrule+
+ % try to account for external frame parameters
+ \FrameSep+\FrameRule+
+ % Usage here of 2 baseline distances is empirical.
+ % In border case where code-block fits barely in remaining space,
+ % it gets framed and looks good but the outer frame may continue
+ % on top of next page and give (if no contents after code-block)
+ % an empty framed line, as testing showed.
+ 2\baselineskip+
+ % now add all to accumulated page totals and compare to \pagegoal
+ \pagetotal+\pagedepth>\pagegoal
+ % long contents: do not \MakeFramed. Do make a caption (either before or
+ % after) if title exists. Continuation hints across pagebreaks dropped.
+ % FIXME? a bottom caption may end up isolated at top of next page
+ % (no problem with a top caption, which is default)
+ \spx@opt@verbatimwithframefalse
+ \def\sphinxVerbatim@Title{\noindent\box\sphinxVerbatim@TitleBox\par}%
+ \sphinxVerbatim@Before
+ \noindent\unvbox\sphinxVerbatim@ContentsBox\par
+ \sphinxVerbatim@After
+ \else
+ % short enough contents: use \MakeFramed. As it is nested, this requires
+ % minipage encapsulation.
+ \noindent\begin{minipage}{\linewidth}%
+ \MakeFramed {% Use it now with the fetched contents
+ \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage
+ }%
+ \unvbox\sphinxVerbatim@ContentsBox
+ % some of this may be superfluous:
+ \par\unskip\@minipagefalse\endMakeFramed
+ \end{minipage}%
+ \fi
+ \else % non-nested \MakeFramed
+ \par\unskip\@minipagefalse\endMakeFramed % from framed.sty snugshade
+ \ifsphinxverbatimwithminipage\end{minipage}\fi
+ \fi
+ \endtrivlist
+}
+\newenvironment {sphinxVerbatimNoFrame}
+ {\spx@opt@verbatimwithframefalse
+ \VerbatimEnvironment
+ \begin{sphinxVerbatim}}
+ {\end{sphinxVerbatim}}
+\newenvironment {sphinxVerbatimintable}
+ {% don't use a frame if in a table cell
+ \spx@opt@verbatimwithframefalse
+ \sphinxverbatimwithminipagetrue
+ % the literal block caption uses \sphinxcaption which is wrapper of \caption,
+ % but \caption must be modified because longtable redefines it to work only
+ % for the own table caption, and tabulary has multiple passes
+ \let\caption\sphinxfigcaption
+ % reduce above caption skip
+ \def\spx@abovecaptionskip{\sphinxverbatimsmallskipamount}%
+ \VerbatimEnvironment
+ \begin{sphinxVerbatim}}
+ {\end{sphinxVerbatim}}
+
+
+%% PARSED LITERALS
+% allow long lines to wrap like they do in code-blocks
+
+% this should be kept in sync with definitions in sphinx.util.texescape
+\newcommand*\sphinxbreaksattexescapedchars{%
+ \def\do##1##2% put potential break point before character
+ {\def##1{\discretionary{}{\sphinxafterbreak\char`##2}{\char`##2}}}%
+ \do\{\{\do\textless\<\do\#\#\do\%\%\do\$\$% {, <, #, %, $
+ \def\do##1##2% put potential break point after character
+ {\def##1{\discretionary{\char`##2}{\sphinxafterbreak}{\char`##2}}}%
+ \do\_\_\do\}\}\do\textasciicircum\^\do\&\&% _, }, ^, &,
+ \do\textgreater\>\do\textasciitilde\~% >, ~
+ \do\textbackslash\\% \
+}
+\newcommand*\sphinxbreaksviaactiveinparsedliteral{%
+ \sphinxbreaksviaactive % by default handles . , ; ? ! /
+ \lccode`\~`\~ %
+ % update \dospecials as it is used by \url
+ % but deactivation will already have been done hence this is unneeded:
+ % \expandafter\def\expandafter\dospecials\expandafter{\dospecials
+ % \sphinxbreaksbeforeactivelist\sphinxbreaksafteractivelist\do\-}%
+}
+\newcommand*\sphinxbreaksatspaceinparsedliteral{%
+ \lccode`~32 \lowercase{\let~}\spx@verbatim@space\lccode`\~`\~
+}
+\newcommand*{\sphinxunactivateextras}{\let\do\@makeother
+ \sphinxbreaksbeforeactivelist\sphinxbreaksafteractivelist}%
+% the \catcode13=5\relax (deactivate end of input lines) is left to callers
+\newcommand*{\sphinxunactivateextrasandspace}{\catcode32=10\relax
+ \sphinxunactivateextras}%
+% now for the modified alltt environment
+\newenvironment{sphinxalltt}
+{% at start of next line to workaround Emacs/AUCTeX issue with this file
+\begin{alltt}%
+ \ifspx@opt@parsedliteralwraps
+ \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
+ \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
+ \sphinxbreaksattexescapedchars
+ \sphinxbreaksviaactiveinparsedliteral
+ \sphinxbreaksatspaceinparsedliteral
+% alltt takes care of the ' as derivative ("prime") in math mode
+ \everymath\expandafter{\the\everymath\sphinxunactivateextrasandspace
+ \catcode`\<=12\catcode`\>=12\catcode`\^=7\catcode`\_=8 }%
+% not sure if displayed math (align,...) can end up in parsed-literal, anyway
+ \everydisplay\expandafter{\the\everydisplay
+ \catcode13=5 \sphinxunactivateextrasandspace
+ \catcode`\<=12\catcode`\>=12\catcode`\^=7\catcode`\_=8 }%
+ \fi }
+{\end{alltt}}
+
+
+%% INLINE MARK-UP
+%
+
+% Protect \href's first argument in contexts such as sphinxalltt (or
+% \sphinxcode). Sphinx uses \#, \%, \& ... always inside \sphinxhref.
+\protected\def\sphinxhref#1#2{{%
+ \sphinxunactivateextrasandspace % never do \scantokens with active space!
+% for the \endlinechar business, https://github.com/latex3/latex2e/issues/286
+ \endlinechar\m@ne\everyeof{{\endlinechar13 #2}}% keep catcode regime for #2
+ \scantokens{\href{#1}}% normalise it for #1 during \href expansion
+}}
+% Same for \url. And also \nolinkurl for coherence.
+\protected\def\sphinxurl#1{{%
+ \sphinxunactivateextrasandspace\everyeof{}% (<- precaution for \scantokens)
+ \endlinechar\m@ne\scantokens{\url{#1}}%
+}}
+\protected\def\sphinxnolinkurl#1{{%
+ \sphinxunactivateextrasandspace\everyeof{}%
+ \endlinechar\m@ne\scantokens{\nolinkurl{#1}}%
+}}
+
+% \sphinxupquote
+% to obtain straight quotes we execute \@noligs as patched by upquote, and
+% \scantokens is needed in cases where it would be too late for the macro to
+% first set catcodes and then fetch its argument. We also make the contents
+% breakable at non-escaped . , ; ? ! / using \sphinxbreaksviaactive,
+% and also at \ character (which is escaped to \textbackslash{}).
+\protected\def\sphinxtextbackslashbreakbefore
+ {\discretionary{}{\sphinxafterbreak\sphinx@textbackslash}{\sphinx@textbackslash}}
+\protected\def\sphinxtextbackslashbreakafter
+ {\discretionary{\sphinx@textbackslash}{\sphinxafterbreak}{\sphinx@textbackslash}}
+\let\sphinxtextbackslash\sphinxtextbackslashbreakafter
+% the macro must be protected if it ends up used in moving arguments,
+% in 'alltt' \@noligs is done already, and the \scantokens must be avoided.
+\protected\def\sphinxupquote#1{{\def\@tempa{alltt}%
+ \ifx\@tempa\@currenvir\else
+ \ifspx@opt@inlineliteralwraps
+ % break at . , ; ? ! /
+ \sphinxbreaksviaactive
+ % break also at \
+ \let\sphinx@textbackslash\textbackslash
+ \let\textbackslash\sphinxtextbackslash
+ % by default, no continuation symbol on next line but may be added
+ \let\sphinxafterbreak\sphinxafterbreakofinlineliteral
+ % do not overwrite the comma set-up
+ \let\verbatim@nolig@list\sphinx@literal@nolig@list
+ \fi
+ % fix a space-gobbling issue due to LaTeX's original \do@noligs
+% TODO: using \@noligs as patched by upquote.sty is now unneeded because
+% either ` and ' are escaped (non-unicode engines) or they don't build
+% ligatures (unicode engines). Thus remove this and unify handling of `, <, >,
+% ' and - with the characters . , ; ? ! / as handled via
+% \sphinxbreaksviaactive.
+% Hence \sphinx@do@noligs will be removed, or rather replaced with code
+% inserting discretionaries, as they allow a continuation symbol on start of
+% next line to achieve common design with code-blocks.
+ \let\do@noligs\sphinx@do@noligs
+ \@noligs\endlinechar\m@ne\everyeof{}% (<- in case inside \sphinxhref)
+ \expandafter\scantokens
+ \fi {{#1}}}}% extra brace pair to fix end-space gobbling issue...
+\def\sphinx@do@noligs #1{\catcode`#1\active\begingroup\lccode`\~`#1\relax
+ \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1 }}}
+\def\sphinx@literal@nolig@list {\do\`\do\<\do\>\do\'\do\-}%
+\let\sphinxafterbreakofinlineliteral\empty
+
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexnumfig.sty b/sphinx/texinputs/sphinxlatexnumfig.sty
new file mode 100644
index 0000000000..6d72961051
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexnumfig.sty
@@ -0,0 +1,122 @@
+%% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexnumfig.sty}[2021/01/27 numbering]
+
+% Requires: remreset (old LaTeX only)
+% relates to numfig and numfig_secnum_depth configuration variables
+
+% LaTeX 2018-04-01 and later provides \@removefromreset
+\ltx@ifundefined{@removefromreset}
+ {\RequirePackage{remreset}}
+ {}% avoid warning
+% Everything is delayed to \begin{document} to allow hyperref patches into
+% \newcounter to solve duplicate label problems for internal hyperlinks to
+% code listings (literalblock counter). User or extension re-definitions of
+% \theliteralblock, et al., thus have also to be delayed. (changed at 3.5.0)
+\AtBeginDocument{%
+\ltx@ifundefined{c@chapter}
+ {\newcounter{literalblock}}%
+ {\newcounter{literalblock}[chapter]%
+ \def\theliteralblock{\ifnum\c@chapter>\z@\arabic{chapter}.\fi
+ \arabic{literalblock}}%
+ }%
+\ifspx@opt@nonumfigreset
+ \ltx@ifundefined{c@chapter}{}{%
+ \@removefromreset{figure}{chapter}%
+ \@removefromreset{table}{chapter}%
+ \@removefromreset{literalblock}{chapter}%
+ \ifspx@opt@mathnumfig
+ \@removefromreset{equation}{chapter}%
+ \fi
+ }%
+ \def\thefigure{\arabic{figure}}%
+ \def\thetable {\arabic{table}}%
+ \def\theliteralblock{\arabic{literalblock}}%
+ \ifspx@opt@mathnumfig
+ \def\theequation{\arabic{equation}}%
+ \fi
+\else
+\let\spx@preAthefigure\@empty
+\let\spx@preBthefigure\@empty
+% \ifspx@opt@usespart % <-- LaTeX writer could pass such a 'usespart' boolean
+% % as sphinx.sty package option
+% If document uses \part, (triggered in Sphinx by latex_toplevel_sectioning)
+% LaTeX core per default does not reset chapter or section
+% counters at each part.
+% But if we modify this, we need to redefine \thechapter, \thesection to
+% include the part number and this will cause problems in table of contents
+% because of too wide numbering. Simplest is to do nothing.
+% \fi
+\ifnum\spx@opt@numfigreset>0
+ \ltx@ifundefined{c@chapter}
+ {}
+ {\g@addto@macro\spx@preAthefigure{\ifnum\c@chapter>\z@\arabic{chapter}.}%
+ \g@addto@macro\spx@preBthefigure{\fi}}%
+\fi
+\ifnum\spx@opt@numfigreset>1
+ \@addtoreset{figure}{section}%
+ \@addtoreset{table}{section}%
+ \@addtoreset{literalblock}{section}%
+ \ifspx@opt@mathnumfig
+ \@addtoreset{equation}{section}%
+ \fi%
+ \g@addto@macro\spx@preAthefigure{\ifnum\c@section>\z@\arabic{section}.}%
+ \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\ifnum\spx@opt@numfigreset>2
+ \@addtoreset{figure}{subsection}%
+ \@addtoreset{table}{subsection}%
+ \@addtoreset{literalblock}{subsection}%
+ \ifspx@opt@mathnumfig
+ \@addtoreset{equation}{subsection}%
+ \fi%
+ \g@addto@macro\spx@preAthefigure{\ifnum\c@subsection>\z@\arabic{subsection}.}%
+ \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\ifnum\spx@opt@numfigreset>3
+ \@addtoreset{figure}{subsubsection}%
+ \@addtoreset{table}{subsubsection}%
+ \@addtoreset{literalblock}{subsubsection}%
+ \ifspx@opt@mathnumfig
+ \@addtoreset{equation}{subsubsection}%
+ \fi%
+ \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubsection>\z@\arabic{subsubsection}.}%
+ \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\ifnum\spx@opt@numfigreset>4
+ \@addtoreset{figure}{paragraph}%
+ \@addtoreset{table}{paragraph}%
+ \@addtoreset{literalblock}{paragraph}%
+ \ifspx@opt@mathnumfig
+ \@addtoreset{equation}{paragraph}%
+ \fi%
+ \g@addto@macro\spx@preAthefigure{\ifnum\c@subparagraph>\z@\arabic{subparagraph}.}%
+ \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\ifnum\spx@opt@numfigreset>5
+ \@addtoreset{figure}{subparagraph}%
+ \@addtoreset{table}{subparagraph}%
+ \@addtoreset{literalblock}{subparagraph}%
+ \ifspx@opt@mathnumfig
+ \@addtoreset{equation}{subparagraph}%
+ \fi%
+ \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubparagraph>\z@\arabic{subsubparagraph}.}%
+ \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\expandafter\g@addto@macro
+\expandafter\spx@preAthefigure\expandafter{\spx@preBthefigure}%
+\let\thefigure\spx@preAthefigure
+\let\thetable\spx@preAthefigure
+\let\theliteralblock\spx@preAthefigure
+\g@addto@macro\thefigure{\arabic{figure}}%
+\g@addto@macro\thetable{\arabic{table}}%
+\g@addto@macro\theliteralblock{\arabic{literalblock}}%
+ \ifspx@opt@mathnumfig
+ \let\theequation\spx@preAthefigure
+ \g@addto@macro\theequation{\arabic{equation}}%
+ \fi
+\fi
+}% end of big \AtBeginDocument
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexobjects.sty b/sphinx/texinputs/sphinxlatexobjects.sty
new file mode 100644
index 0000000000..26e2862c11
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexobjects.sty
@@ -0,0 +1,177 @@
+%% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexobjects.sty}[2021/01/27 documentation environments]
+
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - environments
+%
+% - fulllineitems
+% - productionlist
+% - optionlist
+% - DUlineblock (also "lineblock")
+%
+% - macros
+%
+% - \DUrole
+% - various legacy support macros related to author and release
+% data of documented objects and modules.
+
+% \moduleauthor{name}{email}
+\newcommand{\moduleauthor}[2]{}
+
+% \sectionauthor{name}{email}
+\newcommand{\sectionauthor}[2]{}
+
+% Allow the release number to be specified independently of the
+% \date{}. This allows the date to reflect the document's date and
+% release to specify the release that is documented.
+%
+\newcommand{\py@release}{\releasename\space\version}
+\newcommand{\version}{}% part of \py@release, used by title page and headers
+% \releaseinfo is used on titlepage (sphinxmanual.cls, sphinxhowto.cls)
+\newcommand{\releaseinfo}{}
+\newcommand{\setreleaseinfo}[1]{\renewcommand{\releaseinfo}{#1}}
+% this is inserted via template and #1=release config variable
+\newcommand{\release}[1]{\renewcommand{\version}{#1}}
+% this is defined by template to 'releasename' latex_elements key
+\newcommand{\releasename}{}
+% Fix issue in case release and releasename deliberately left blank
+\newcommand{\sphinxheadercomma}{, }% used in fancyhdr header definition
+\newcommand{\sphinxifemptyorblank}[1]{%
+% test after one expansion of macro #1 if contents is empty or spaces
+ \if&\expandafter\@firstofone\detokenize\expandafter{#1}&%
+ \expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}%
+\AtBeginDocument {%
+ \sphinxifemptyorblank{\releasename}
+ {\sphinxifemptyorblank{\version}{\let\sphinxheadercomma\empty}{}}
+ {}%
+}%
+
+% Allow specification of the author's address separately from the
+% author's name. This can be used to format them differently, which
+% is a good thing.
+%
+\newcommand{\py@authoraddress}{}
+\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
+
+% {fulllineitems} is the main environment for object descriptions.
+%
+\newcommand{\py@itemnewline}[1]{%
+ \kern\labelsep
+ \@tempdima\linewidth
+ \advance\@tempdima \labelwidth\makebox[\@tempdima][l]{#1}%
+ \kern-\labelsep
+}
+
+\newenvironment{fulllineitems}{%
+ \begin{list}{}{\labelwidth \leftmargin
+ \rightmargin \z@ \topsep -\parskip \partopsep \parskip
+ \itemsep -\parsep
+ \let\makelabel=\py@itemnewline}%
+}{\end{list}}
+
+% Signatures, possibly multi-line
+%
+\newlength{\py@argswidth}
+\newcommand{\py@sigparams}[2]{%
+ \parbox[t]{\py@argswidth}{#1\sphinxcode{)}#2}}
+\newcommand{\pysigline}[1]{\item[{#1}]}
+\newcommand{\pysiglinewithargsret}[3]{%
+ \settowidth{\py@argswidth}{#1\sphinxcode{(}}%
+ \addtolength{\py@argswidth}{-2\py@argswidth}%
+ \addtolength{\py@argswidth}{\linewidth}%
+ \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}}]}
+\newcommand{\pysigstartmultiline}{%
+ \def\pysigstartmultiline{\vskip\smallskipamount\parskip\z@skip\itemsep\z@skip}%
+ \edef\pysigstopmultiline
+ {\noexpand\leavevmode\parskip\the\parskip\relax\itemsep\the\itemsep\relax}%
+ \parskip\z@skip\itemsep\z@skip
+}
+
+% Production lists
+%
+\newenvironment{productionlist}{%
+% \def\sphinxoptional##1{{\Large[}##1{\Large]}}
+ \def\production##1##2{\\\sphinxcode{\sphinxupquote{##1}}&::=&\sphinxcode{\sphinxupquote{##2}}}%
+ \def\productioncont##1{\\& &\sphinxcode{\sphinxupquote{##1}}}%
+ \parindent=2em
+ \indent
+ \setlength{\LTpre}{0pt}%
+ \setlength{\LTpost}{0pt}%
+ \begin{longtable}[l]{lcl}
+}{%
+ \end{longtable}
+}
+
+% Definition lists; requested by AMK for HOWTO documents. Probably useful
+% elsewhere as well, so keep in in the general style support.
+%
+\newenvironment{definitions}{%
+ \begin{description}%
+ \def\term##1{\item[{##1}]\mbox{}\\*[0mm]}%
+}{%
+ \end{description}%
+}
+
+%% FROM DOCTUTILS LATEX WRITER
+%
+% The following is stuff copied from docutils' latex writer.
+%
+\newcommand{\optionlistlabel}[1]{\normalfont\bfseries #1 \hfill}% \bf deprecated
+\newenvironment{optionlist}[1]
+{\begin{list}{}
+ {\setlength{\labelwidth}{#1}
+ \setlength{\rightmargin}{1cm}
+ \setlength{\leftmargin}{\rightmargin}
+ \addtolength{\leftmargin}{\labelwidth}
+ \addtolength{\leftmargin}{\labelsep}
+ \renewcommand{\makelabel}{\optionlistlabel}}
+}{\end{list}}
+
+\newlength{\lineblockindentation}
+\setlength{\lineblockindentation}{2.5em}
+\newenvironment{lineblock}[1]
+{\begin{list}{}
+ {\setlength{\partopsep}{\parskip}
+ \addtolength{\partopsep}{\baselineskip}
+ \topsep0pt\itemsep0.15\baselineskip\parsep0pt
+ \leftmargin#1\relax}
+ \raggedright}
+{\end{list}}
+
+% From docutils.writers.latex2e
+% inline markup (custom roles)
+% \DUrole{#1}{#2} tries \DUrole#1{#2}
+\providecommand*{\DUrole}[2]{%
+ \ifcsname DUrole\detokenize{#1}\endcsname
+ \csname DUrole\detokenize{#1}\endcsname{#2}%
+ \else% backwards compatibility: try \docutilsrole#1{#2}
+ \ifcsname docutilsrole\detokenize{#1}\endcsname
+ \csname docutilsrole\detokenize{#1}\endcsname{#2}%
+ \else
+ #2%
+ \fi
+ \fi
+}
+
+\providecommand*{\DUprovidelength}[2]{%
+ \ifdefined#1\else\newlength{#1}\setlength{#1}{#2}\fi
+}
+
+\DUprovidelength{\DUlineblockindent}{2.5em}
+\ifdefined\DUlineblock\else
+ \newenvironment{DUlineblock}[1]{%
+ \list{}{\setlength{\partopsep}{\parskip}
+ \addtolength{\partopsep}{\baselineskip}
+ \setlength{\topsep}{0pt}
+ \setlength{\itemsep}{0.15\baselineskip}
+ \setlength{\parsep}{0pt}
+ \setlength{\leftmargin}{#1}}
+ \raggedright
+ }
+ {\endlist}
+\fi
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty
new file mode 100644
index 0000000000..8d6c78666c
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexshadowbox.sty
@@ -0,0 +1,100 @@
+%% TOPIC AND CONTENTS BOXES
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexshadowbox.sty}[2021/01/27 sphinxShadowBox]
+
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - sphinxShadowBox (environment)
+%
+% Dependencies (they do not need to be defined at time of loading):
+%
+% - of course the various colour and dimension options handled via sphinx.sty
+% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
+% - \savenotes/\spewnotes from sphinxpackagefootnote
+% - \ifspx@inframed defined in sphinx.sty
+%
+% Requires:
+\RequirePackage{framed}
+
+% Again based on use of "framed.sty", this allows breakable framed boxes.
+\long\def\spx@ShadowFBox#1{%
+ \leavevmode\begingroup
+ % first we frame the box #1
+ \setbox\@tempboxa
+ \hbox{\vrule\@width\sphinxshadowrule
+ \vbox{\hrule\@height\sphinxshadowrule
+ \kern\sphinxshadowsep
+ \hbox{\kern\sphinxshadowsep #1\kern\sphinxshadowsep}%
+ \kern\sphinxshadowsep
+ \hrule\@height\sphinxshadowrule}%
+ \vrule\@width\sphinxshadowrule}%
+ % Now we add the shadow, like \shadowbox from fancybox.sty would do
+ \dimen@\dimexpr.5\sphinxshadowrule+\sphinxshadowsize\relax
+ \hbox{\vbox{\offinterlineskip
+ \hbox{\copy\@tempboxa\kern-.5\sphinxshadowrule
+ % add shadow on right side
+ \lower\sphinxshadowsize
+ \hbox{\vrule\@height\ht\@tempboxa \@width\dimen@}%
+ }%
+ \kern-\dimen@ % shift back vertically to bottom of frame
+ % and add shadow at bottom
+ \moveright\sphinxshadowsize
+ \vbox{\hrule\@width\wd\@tempboxa \@height\dimen@}%
+ }%
+ % move left by the size of right shadow so shadow adds no width
+ \kern-\sphinxshadowsize
+ }%
+ \endgroup
+}
+
+% use framed.sty to allow page breaks in frame+shadow
+% works well inside Lists and Quote-like environments
+% produced by ``topic'' directive (or local contents)
+% could nest if LaTeX writer authorized it
+\newenvironment{sphinxShadowBox}
+ {\def\FrameCommand {\spx@ShadowFBox }%
+ \advance\spx@image@maxheight
+ -\dimexpr2\sphinxshadowrule
+ +2\sphinxshadowsep
+ +\sphinxshadowsize
+ +\baselineskip\relax
+ % configure framed.sty not to add extra vertical spacing
+ \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}%
+ % the \trivlist will add the vertical spacing on top and bottom which is
+ % typical of center environment as used in Sphinx <= 1.4.1
+ % the \noindent has the effet of an extra blank line on top, to
+ % imitate closely the layout from Sphinx <= 1.4.1; the \FrameHeightAdjust
+ % will put top part of frame on this baseline.
+ \def\FrameHeightAdjust {\baselineskip}%
+ % use package footnote to handle footnotes
+ \savenotes
+ \trivlist\item\noindent
+ % use a minipage if we are already inside a framed environment
+ \ifspx@inframed\begin{minipage}{\linewidth}\fi
+ \MakeFramed {\spx@inframedtrue
+ % framed.sty puts into "\width" the added width (=2shadowsep+2shadowrule)
+ % adjust \hsize to what the contents must use
+ \advance\hsize-\width
+ % adjust LaTeX parameters to behave properly in indented/quoted contexts
+ \FrameRestore
+ % typeset the contents as in a minipage (Sphinx <= 1.4.1 used a minipage and
+ % itemize/enumerate are therein typeset more tightly, we want to keep
+ % that). We copy-paste from LaTeX source code but don't do a real minipage.
+ \@pboxswfalse
+ \let\@listdepth\@mplistdepth \@mplistdepth\z@
+ \@minipagerestore
+ \@setminipage
+ }%
+ }%
+ {% insert the "endminipage" code
+ \par\unskip
+ \@minipagefalse
+ \endMakeFramed
+ \ifspx@inframed\end{minipage}\fi
+ \endtrivlist
+ % output the stored footnotes
+ \spewnotes
+ }
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexstyleheadings.sty b/sphinx/texinputs/sphinxlatexstyleheadings.sty
new file mode 100644
index 0000000000..fa9be82b44
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexstyleheadings.sty
@@ -0,0 +1,83 @@
+%% TITLES
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexstyleheadings.sty}[2021/01/27 headings]
+
+\RequirePackage[nobottomtitles*]{titlesec}
+\@ifpackagelater{titlesec}{2016/03/15}%
+ {\@ifpackagelater{titlesec}{2016/03/21}%
+ {}%
+ {\newif\ifsphinx@ttlpatch@ok
+ \IfFileExists{etoolbox.sty}{%
+ \RequirePackage{etoolbox}%
+ \patchcmd{\ttlh@hang}{\parindent\z@}{\parindent\z@\leavevmode}%
+ {\sphinx@ttlpatch@oktrue}{}%
+ \ifsphinx@ttlpatch@ok
+ \patchcmd{\ttlh@hang}{\noindent}{}{}{\sphinx@ttlpatch@okfalse}%
+ \fi
+ }{}%
+ \ifsphinx@ttlpatch@ok
+ \typeout{^^J Package Sphinx Info: ^^J
+ **** titlesec 2.10.1 successfully patched for bugfix ****^^J}%
+ \else
+ \AtEndDocument{\PackageWarningNoLine{sphinx}{^^J%
+******** titlesec 2.10.1 has a bug, (section numbers disappear) ......|^^J%
+******** and Sphinx could not patch it, perhaps because your local ...|^^J%
+******** copy is already fixed without a changed release date. .......|^^J%
+******** If not, you must update titlesec! ...........................|}}%
+ \fi
+ }%
+ }{}
+
+% Augment the sectioning commands used to get our own font family in place,
+% and reset some internal data items (\titleformat from titlesec package)
+\titleformat{\section}{\Large\py@HeaderFamily}%
+ {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}
+\titleformat{\subsection}{\large\py@HeaderFamily}%
+ {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}
+\titleformat{\subsubsection}{\py@HeaderFamily}%
+ {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}
+% By default paragraphs (and subsubsections) will not be numbered because
+% sphinxmanual.cls and sphinxhowto.cls set secnumdepth to 2
+\titleformat{\paragraph}{\py@HeaderFamily}%
+ {\py@TitleColor\theparagraph}{0.5em}{\py@TitleColor}
+\titleformat{\subparagraph}{\py@HeaderFamily}%
+ {\py@TitleColor\thesubparagraph}{0.5em}{\py@TitleColor}
+
+
+% Since Sphinx 1.5, users should use HeaderFamily key to 'sphinxsetup' rather
+% than defining their own \py@HeaderFamily command (which is still possible).
+% Memo: \py@HeaderFamily is also used by \maketitle as defined in
+% sphinxmanual.cls/sphinxhowto.cls
+\newcommand{\py@HeaderFamily}{\spx@opt@HeaderFamily}
+
+% This sets up the fancy chapter headings that make the documents look
+% at least a little better than the usual LaTeX output.
+\@ifpackagewith{fncychap}{Bjarne}{
+ \ChNameVar {\raggedleft\normalsize \py@HeaderFamily}
+ \ChNumVar {\raggedleft\Large \py@HeaderFamily}
+ \ChTitleVar{\raggedleft\Large \py@HeaderFamily}
+ % This creates (numbered) chapter heads without the leading \vspace*{}:
+ \def\@makechapterhead#1{%
+ {\parindent \z@ \raggedright \normalfont
+ \ifnum \c@secnumdepth >\m@ne
+ \if@mainmatter
+ \DOCH
+ \fi
+ \fi
+ \interlinepenalty\@M
+ \if@mainmatter
+ \DOTI{#1}%
+ \else%
+ \DOTIS{#1}%
+ \fi
+ }}
+}{}% <-- "false" clause of \@ifpackagewith
+
+% fix fncychap's bug which uses prematurely the \textwidth value
+\@ifpackagewith{fncychap}{Bjornstrup}
+ {\AtBeginDocument{\mylen\textwidth\advance\mylen-2\myhi}}%
+ {}% <-- "false" clause of \@ifpackagewith
+
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexstylepage.sty b/sphinx/texinputs/sphinxlatexstylepage.sty
new file mode 100644
index 0000000000..4066129bf2
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexstylepage.sty
@@ -0,0 +1,79 @@
+%% PAGE STYLING
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexstylepage.sty}[2021/01/27 page styling]
+
+% Separate paragraphs by space by default.
+\IfFileExists{parskip-2001-04-09.sty}% since September 2018 TeXLive update
+% new parskip.sty, but let it rollback to old one.
+% hopefully TeX installation not broken and LaTeX kernel not too old
+ {\RequirePackage{parskip}[=v1]}
+% standard one from 1989. Admittedly \section of article/book gives possibly
+% anomalous spacing, but we can't require September 2018 release for some time.
+ {\RequirePackage{parskip}}
+
+% Style parameters and macros used by most documents here
+\raggedbottom
+\sloppy
+\hbadness = 5000 % don't print trivial gripes
+
+% Require package fancyhdr except under memoir class
+\@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}}
+% Use \pagestyle{normal} as the primary pagestyle for text.
+% Redefine the 'normal' header/footer style when using "fancyhdr" package:
+\@ifpackageloaded{fancyhdr}{%
+ \ltx@ifundefined{c@chapter}
+ {% no \chapter, "howto" (non-Japanese) docclass
+ \fancypagestyle{plain}{
+ \fancyhf{}
+ \fancyfoot[C]{{\py@HeaderFamily\thepage}}
+ \renewcommand{\headrulewidth}{0pt}
+ \renewcommand{\footrulewidth}{0pt}
+ }
+ % Same as 'plain', this way we can use it in template
+ % FIXME: shouldn't this have a running header with Name and Release like 'manual'?
+ \fancypagestyle{normal}{
+ \fancyhf{}
+ \fancyfoot[C]{{\py@HeaderFamily\thepage}}
+ \renewcommand{\headrulewidth}{0pt}
+ \renewcommand{\footrulewidth}{0pt}
+ }
+ }%
+ {% classes with \chapter command
+ \fancypagestyle{normal}{
+ \fancyhf{}
+ \fancyfoot[RO]{{\py@HeaderFamily\thepage}}
+ \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
+ \fancyhead[RO]{{\py@HeaderFamily \@title\sphinxheadercomma\py@release}}
+ \if@twoside
+ \fancyfoot[LE]{{\py@HeaderFamily\thepage}}
+ \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
+ \fancyhead[LE]{{\py@HeaderFamily \@title\sphinxheadercomma\py@release}}
+ \fi
+ \renewcommand{\headrulewidth}{0.4pt}
+ \renewcommand{\footrulewidth}{0.4pt}
+ % define chaptermark with \@chappos when \@chappos is available for Japanese
+ \ltx@ifundefined{@chappos}{}
+ {\def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}}}
+ }
+ % Update the plain style so we get the page number & footer line,
+ % but not a chapter or section title. This is to keep the first
+ % page of a chapter `clean.'
+ \fancypagestyle{plain}{
+ \fancyhf{}
+ \fancyfoot[RO]{{\py@HeaderFamily\thepage}}
+ \if@twoside\fancyfoot[LE]{{\py@HeaderFamily\thepage}}\fi
+ \renewcommand{\headrulewidth}{0pt}
+ \renewcommand{\footrulewidth}{0.4pt}
+ }
+ }
+ }
+ {% no fancyhdr: memoir class
+ % Provide default for 'normal' style simply as an alias of 'plain' style
+ % This way we can use \pagestyle{normal} in LaTeX template
+ \def\ps@normal{\ps@plain}
+ % Users of memoir class are invited to redefine 'normal' style in preamble
+ }
+
+
+\endinput
diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty
new file mode 100644
index 0000000000..ab50aed569
--- /dev/null
+++ b/sphinx/texinputs/sphinxlatexstyletext.sty
@@ -0,0 +1,126 @@
+%% TEXT STYLING
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatexstyletext.sty}[2021/01/27 text styling]
+
+% Basically everything here consists of macros which are part of the latex
+% markup produced by the Sphinx latex writer
+
+% Some custom font markup commands.
+\protected\def\sphinxstrong#1{\textbf{#1}}
+\protected\def\sphinxcode#1{\texttt{#1}}
+\protected\def\sphinxbfcode#1{\textbf{\sphinxcode{#1}}}
+\protected\def\sphinxemail#1{\textsf{#1}}
+\protected\def\sphinxtablecontinued#1{\textsf{#1}}
+\protected\def\sphinxtitleref#1{\emph{#1}}
+\protected\def\sphinxmenuselection#1{\emph{#1}}
+\protected\def\sphinxguilabel#1{\emph{#1}}
+\protected\def\sphinxkeyboard#1{\sphinxcode{#1}}
+\protected\def\sphinxaccelerator#1{\underline{#1}}
+\protected\def\sphinxcrossref#1{\emph{#1}}
+\protected\def\sphinxtermref#1{\emph{#1}}
+% \optional is used for ``[, arg]``, i.e. desc_optional nodes.
+\long\protected\def\sphinxoptional#1{%
+ {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
+
+% additional customizable styling
+\def\sphinxstyleindexentry #1{\texttt{#1}}
+\def\sphinxstyleindexextra #1{ (\emph{#1})}
+\def\sphinxstyleindexpageref #1{, \pageref{#1}}
+\def\sphinxstyleindexpagemain#1{\textbf{#1}}
+\def\spxentry{\@backslashchar spxentry}% let to \sphinxstyleindexentry in index
+\def\spxextra{\@backslashchar spxextra}% let to \sphinxstyleindexextra in index
+\def\sphinxstyleindexlettergroup #1%
+ {{\Large\sffamily#1}\nopagebreak\vspace{1mm}}
+\def\sphinxstyleindexlettergroupDefault #1%
+ {{\Large\sffamily\sphinxnonalphabeticalgroupname}\nopagebreak\vspace{1mm}}
+\protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip}
+\let\sphinxstylesidebartitle\sphinxstyletopictitle
+\protected\def\sphinxstyleothertitle #1{\textbf{#1}}
+\protected\def\sphinxstylesidebarsubtitle #1{~\\\textbf{#1} \smallskip}
+% \text.. commands do not allow multiple paragraphs
+\protected\def\sphinxstyletheadfamily {\sffamily}
+\protected\def\sphinxstyleemphasis #1{\emph{#1}}
+\protected\def\sphinxstyleliteralemphasis#1{\emph{\sphinxcode{#1}}}
+\protected\def\sphinxstylestrong #1{\textbf{#1}}
+\protected\def\sphinxstyleliteralstrong#1{\sphinxbfcode{#1}}
+\protected\def\sphinxstyleabbreviation #1{\textsc{#1}}
+\protected\def\sphinxstyleliteralintitle#1{\sphinxcode{#1}}
+\newcommand*\sphinxstylecodecontinued[1]{\footnotesize(#1)}%
+\newcommand*\sphinxstylecodecontinues[1]{\footnotesize(#1)}%
+% figure legend comes after caption and may contain arbitrary body elements
+\newenvironment{sphinxlegend}{\par\small}{\par}
+% reduce hyperref "Token not allowed in a PDF string" warnings on PDF builds
+\AtBeginDocument{\pdfstringdefDisableCommands{%
+% all "protected" macros possibly ending up in section titles should be here
+% TODO: examine if \sphinxhref, \sphinxurl, \sphinnolinkurl should be handled
+ \let\sphinxstyleemphasis \@firstofone
+ \let\sphinxstyleliteralemphasis \@firstofone
+ \let\sphinxstylestrong \@firstofone
+ \let\sphinxstyleliteralstrong \@firstofone
+ \let\sphinxstyleabbreviation \@firstofone
+ \let\sphinxstyleliteralintitle \@firstofone
+ \let\sphinxupquote \@firstofone
+ \let\sphinxstrong \@firstofone
+ \let\sphinxcode \@firstofone
+ \let\sphinxbfcode \@firstofone
+ \let\sphinxemail \@firstofone
+ \let\sphinxcrossref \@firstofone
+ \let\sphinxtermref \@firstofone
+ \let\sphinxhyphen\sphinxhyphenforbookmarks
+}}
+
+% Special characters
+%
+% This definition prevents en-dash and em-dash TeX ligatures.
+%
+% It inserts a potential breakpoint after the hyphen. This is to keep in sync
+% with behavior in code-blocks, parsed and inline literals. For a breakpoint
+% before the hyphen use \leavevmode\kern\z@- (within \makeatletter/\makeatother)
+\protected\def\sphinxhyphen#1{-\kern\z@}
+% The {} from texescape mark-up is kept, else -- gives en-dash in PDF bookmark
+\def\sphinxhyphenforbookmarks{-}
+
+% For curly braces inside \index macro
+\def\sphinxleftcurlybrace{\{}
+\def\sphinxrightcurlybrace{\}}
+
+% Declare Unicode characters used by linux tree command to pdflatex utf8/utf8x
+\def\spx@bd#1#2{%
+ \leavevmode
+ \begingroup
+ \ifx\spx@bd@height \@undefined\def\spx@bd@height{\baselineskip}\fi
+ \ifx\spx@bd@width \@undefined\setbox0\hbox{0}\def\spx@bd@width{\wd0 }\fi
+ \ifx\spx@bd@thickness\@undefined\def\spx@bd@thickness{.6\p@}\fi
+ \ifx\spx@bd@lower \@undefined\def\spx@bd@lower{\dp\strutbox}\fi
+ \lower\spx@bd@lower#1{#2}%
+ \endgroup
+}%
+\@namedef{sphinx@u2500}% BOX DRAWINGS LIGHT HORIZONTAL
+ {\spx@bd{\vbox to\spx@bd@height}
+ {\vss\hrule\@height\spx@bd@thickness
+ \@width\spx@bd@width\vss}}%
+\@namedef{sphinx@u2502}% BOX DRAWINGS LIGHT VERTICAL
+ {\spx@bd{\hb@xt@\spx@bd@width}
+ {\hss\vrule\@height\spx@bd@height
+ \@width \spx@bd@thickness\hss}}%
+\@namedef{sphinx@u2514}% BOX DRAWINGS LIGHT UP AND RIGHT
+ {\spx@bd{\hb@xt@\spx@bd@width}
+ {\hss\raise.5\spx@bd@height
+ \hb@xt@\z@{\hss\vrule\@height.5\spx@bd@height
+ \@width \spx@bd@thickness\hss}%
+ \vbox to\spx@bd@height{\vss\hrule\@height\spx@bd@thickness
+ \@width.5\spx@bd@width\vss}}}%
+\@namedef{sphinx@u251C}% BOX DRAWINGS LIGHT VERTICAL AND RIGHT
+ {\spx@bd{\hb@xt@\spx@bd@width}
+ {\hss
+ \hb@xt@\z@{\hss\vrule\@height\spx@bd@height
+ \@width \spx@bd@thickness\hss}%
+ \vbox to\spx@bd@height{\vss\hrule\@height\spx@bd@thickness
+ \@width.5\spx@bd@width\vss}}}%
+\protected\def\sphinxunichar#1{\@nameuse{sphinx@u#1}}%
+
+% Tell TeX about pathological hyphenation cases:
+\hyphenation{Base-HTTP-Re-quest-Hand-ler}
+
+\endinput
diff --git a/sphinx/texinputs/sphinxmulticell.sty b/sphinx/texinputs/sphinxlatextables.sty
similarity index 65%
rename from sphinx/texinputs/sphinxmulticell.sty
rename to sphinx/texinputs/sphinxlatextables.sty
index a6454918f3..c3c1d6ad1f 100644
--- a/sphinx/texinputs/sphinxmulticell.sty
+++ b/sphinx/texinputs/sphinxlatextables.sty
@@ -1,9 +1,173 @@
-\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{sphinxmulticell}%
- [2017/02/23 v1.6 better span rows and columns of a table (Sphinx team)]%
-\DeclareOption*{\PackageWarning{sphinxmulticell}{Option `\CurrentOption' is unknown}}%
-\ProcessOptions\relax
+%% TABLES (WITH SUPPORT FOR MERGED CELLS OF GENERAL CONTENTS)
%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxlatextables.sty}[2021/01/27 tables]%
+
+% Provides support for this output mark-up from Sphinx latex writer
+% and table templates:
+%
+% - the tabulary and longtable environments from the eponymous packages
+% - the varwidth environment
+% - the >{} etc mark-up possible in tabularcolumns is from array package
+% which is loaded by longtable and tabulary
+% - \X, \Y, T column types; others (L, C, R, J) are from tabulary package
+% - \sphinxaftertopcaption
+% - \sphinxatlongtableend
+% - \sphinxatlongtablestart
+% - \sphinxattableend
+% - \sphinxattablestart
+% - \sphinxcapstartof
+% - \sphinxcolwidth
+% - \sphinxlongtablecapskipadjust
+% - \sphinxmultirow
+% - \sphinxstartmulticolumn
+% - \sphinxstopmulticolumn
+% - \sphinxtablestrut
+% - \sphinxthecaptionisattop
+% - \sphinxthelongtablecaptionisattop
+%
+% Executes \RequirePackage for:
+%
+% - tabulary
+% - longtable
+% - varwidth
+%
+% Extends tabulary and longtable via patches and custom macros to support
+% merged cells possibly containing code-blocks in complex tables
+
+\RequirePackage{tabulary}
+% tabulary has a bug with its re-definition of \multicolumn in its first pass
+% which is not \long. But now Sphinx does not use LaTeX's \multicolumn but its
+% own macro. Hence we don't even need to patch tabulary. See
+% sphinxpackagemulticell.sty
+% X or S (Sphinx) may have meanings if some table package is loaded hence
+% \X was chosen to avoid possibility of conflict
+\newcolumntype{\X}[2]{p{\dimexpr
+ (\linewidth-\arrayrulewidth)*#1/#2-\tw@\tabcolsep-\arrayrulewidth\relax}}
+\newcolumntype{\Y}[1]{p{\dimexpr
+ #1\dimexpr\linewidth-\arrayrulewidth\relax-\tw@\tabcolsep-\arrayrulewidth\relax}}
+% using here T (for Tabulary) feels less of a problem than the X could be
+\newcolumntype{T}{J}%
+% For tables allowing pagebreaks
+\RequirePackage{longtable}
+% User interface to set-up whitespace before and after tables:
+\newcommand*\sphinxtablepre {0pt}%
+\newcommand*\sphinxtablepost{\medskipamount}%
+% Space from caption baseline to top of table or frame of literal-block
+\newcommand*\sphinxbelowcaptionspace{.5\sphinxbaselineskip}%
+% as one can not use \baselineskip from inside longtable (it is zero there)
+% we need \sphinxbaselineskip, which defaults to \baselineskip
+\def\sphinxbaselineskip{\baselineskip}%
+% The following is to ensure that, whether tabular(y) or longtable:
+% - if a caption is on top of table:
+% a) the space between its last baseline and the top rule of table is
+% exactly \sphinxbelowcaptionspace
+% b) the space from last baseline of previous text to first baseline of
+% caption is exactly \parskip+\baselineskip+ height of a strut.
+% c) the caption text will wrap at width \LTcapwidth (4in)
+% - make sure this works also if "caption" package is loaded by user
+% (with its width or margin option taking place of \LTcapwidth role)
+% TODO: obtain same for caption of literal block: a) & c) DONE, b) TO BE DONE
+%
+% To modify space below such top caption, adjust \sphinxbelowcaptionspace
+% To add or remove space above such top caption, adjust \sphinxtablepre:
+% notice that \abovecaptionskip, \belowcaptionskip, \LTpre are **ignored**
+% A. Table with longtable
+\def\sphinxatlongtablestart
+ {\par
+ \vskip\parskip
+ \vskip\dimexpr\sphinxtablepre\relax % adjust vertical position
+ \vbox{}% get correct baseline from above
+ \LTpre\z@skip\LTpost\z@skip % set to zero longtable's own skips
+ \edef\sphinxbaselineskip{\dimexpr\the\dimexpr\baselineskip\relax\relax}%
+ }%
+% Compatibility with caption package
+\def\sphinxthelongtablecaptionisattop{%
+ \spx@ifcaptionpackage{\noalign{\vskip-\belowcaptionskip}}{}%
+}%
+% Achieves exactly \sphinxbelowcaptionspace below longtable caption
+\def\sphinxlongtablecapskipadjust
+ {\dimexpr-\dp\strutbox
+ -\spx@ifcaptionpackage{\abovecaptionskip}{\sphinxbaselineskip}%
+ +\sphinxbelowcaptionspace\relax}%
+\def\sphinxatlongtableend{\@nobreakfalse % latex3/latex2e#173
+ \prevdepth\z@\vskip\sphinxtablepost\relax}%
+% B. Table with tabular or tabulary
+\def\sphinxattablestart{\par\vskip\dimexpr\sphinxtablepre\relax}%
+\let\sphinxattableend\sphinxatlongtableend
+% This is used by tabular and tabulary templates
+\newcommand*\sphinxcapstartof[1]{%
+ \vskip\parskip
+ \vbox{}% force baselineskip for good positioning by capstart of hyperanchor
+ % hyperref puts the anchor 6pt above this baseline; in case of caption
+ % this baseline will be \ht\strutbox above first baseline of caption
+ \def\@captype{#1}%
+ \capstart
+% move back vertically, as tabular (or its caption) will compensate
+ \vskip-\baselineskip\vskip-\parskip
+}%
+\def\sphinxthecaptionisattop{% locate it after \sphinxcapstartof
+ \spx@ifcaptionpackage
+ {\caption@setposition{t}%
+ \vskip\baselineskip\vskip\parskip % undo those from \sphinxcapstartof
+ \vskip-\belowcaptionskip % anticipate caption package skip
+ % caption package uses a \vbox, not a \vtop, so "single line" case
+ % gives different result from "multi-line" without this:
+ \nointerlineskip
+ }%
+ {}%
+}%
+\def\sphinxthecaptionisatbottom{% (not finalized; for template usage)
+ \spx@ifcaptionpackage{\caption@setposition{b}}{}%
+}%
+% The aim of \sphinxcaption is to apply to tabular(y) the maximal width
+% of caption as done by longtable
+\def\sphinxtablecapwidth{\LTcapwidth}%
+\newcommand\sphinxcaption{\@dblarg\spx@caption}%
+\long\def\spx@caption[#1]#2{%
+ \noindent\hb@xt@\linewidth{\hss
+ \vtop{\@tempdima\dimexpr\sphinxtablecapwidth\relax
+% don't exceed linewidth for the caption width
+ \ifdim\@tempdima>\linewidth\hsize\linewidth\else\hsize\@tempdima\fi
+% longtable ignores \abovecaptionskip/\belowcaptionskip, so do the same here
+ \abovecaptionskip\sphinxabovecaptionskip % \z@skip
+ \belowcaptionskip\sphinxbelowcaptionskip % \z@skip
+ \caption[{#1}]%
+ {\strut\ignorespaces#2\ifhmode\unskip\@finalstrut\strutbox\fi}%
+ }\hss}%
+ \par\prevdepth\dp\strutbox
+}%
+\def\sphinxabovecaptionskip{\z@skip}% Do not use! Flagged for removal
+\def\sphinxbelowcaptionskip{\z@skip}% Do not use! Flagged for removal
+% This wrapper of \abovecaptionskip is used in sphinxVerbatim for top
+% caption, and with another value in sphinxVerbatimintable
+% TODO: To unify space above caption of a code-block with the one above
+% caption of a table/longtable, \abovecaptionskip must not be used
+% This auxiliary will get renamed and receive a different meaning
+% in future.
+\def\spx@abovecaptionskip{\abovecaptionskip}%
+% Achieve \sphinxbelowcaptionspace below a caption located above a tabular
+% or a tabulary
+\newcommand\sphinxaftertopcaption
+{%
+ \spx@ifcaptionpackage
+ {\par\prevdepth\dp\strutbox\nobreak\vskip-\abovecaptionskip}{\nobreak}%
+ \vskip\dimexpr\sphinxbelowcaptionspace\relax
+ \vskip-\baselineskip\vskip-\parskip
+}%
+% varwidth is crucial for our handling of general contents in merged cells
+\RequirePackage{varwidth}
+% but addition of a compatibility patch with hyperref is needed
+% (tested with varwidth v 0.92 Mar 2009)
+\AtBeginDocument {%
+ \let\@@vwid@Hy@raisedlink\Hy@raisedlink
+ \long\def\@vwid@Hy@raisedlink#1{\@vwid@wrap{\@@vwid@Hy@raisedlink{#1}}}%
+ \edef\@vwid@setup{%
+ \let\noexpand\Hy@raisedlink\noexpand\@vwid@Hy@raisedlink % HYPERREF !
+ \unexpanded\expandafter{\@vwid@setup}}%
+}%
+
+%%%%%%%%%%%%%%%%%%%%%
% --- MULTICOLUMN ---
% standard LaTeX's \multicolumn
% 1. does not allow verbatim contents,
@@ -205,7 +369,8 @@
\def\sphinx@multiwidth #1#2{\dimexpr % #1 to gobble the \@gobble (!)
(\ifx\TY@final\@undefined\linewidth\else\sphinx@TY@tablewidth\fi
-\arrayrulewidth)*#2-\tw@\tabcolsep-\arrayrulewidth\relax}%
-%
+
+%%%%%%%%%%%%%%%%%%
% --- MULTIROW ---
% standard \multirow
% 1. does not allow verbatim contents,
@@ -312,6 +477,5 @@
% we need this to avoid colour panels hiding bottom parts of multirow text
\sphinx@hack@CT
}%
+
\endinput
-%%
-%% End of file `sphinxmulticell.sty'.
diff --git a/sphinx/texinputs/sphinxoptionsgeometry.sty b/sphinx/texinputs/sphinxoptionsgeometry.sty
new file mode 100644
index 0000000000..af5a804d59
--- /dev/null
+++ b/sphinx/texinputs/sphinxoptionsgeometry.sty
@@ -0,0 +1,54 @@
+%% OPTIONS FOR GEOMETRY
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxoptionsgeometry.sty}[2021/01/27 geometry]
+
+% geometry
+\ifx\kanjiskip\@undefined
+ \PassOptionsToPackage{%
+ hmargin={\unexpanded{\spx@opt@hmargin}},%
+ vmargin={\unexpanded{\spx@opt@vmargin}},%
+ marginpar=\unexpanded{\spx@opt@marginpar}}
+ {geometry}
+\else
+ % set text width for Japanese documents to be integer multiple of 1zw
+ % and text height to be integer multiple of \baselineskip
+ % the execution is delayed to \sphinxsetup then geometry.sty
+ \normalsize\normalfont
+ \newcommand*\sphinxtextwidthja[1]{%
+ \if@twocolumn\tw@\fi
+ \dimexpr
+ \numexpr\dimexpr\paperwidth-\tw@\dimexpr#1\relax\relax/
+ \dimexpr\if@twocolumn\tw@\else\@ne\fi zw\relax
+ zw\relax}%
+ \newcommand*\sphinxmarginparwidthja[1]{%
+ \dimexpr\numexpr\dimexpr#1\relax/\dimexpr1zw\relax zw\relax}%
+ \newcommand*\sphinxtextlinesja[1]{%
+ \numexpr\@ne+\dimexpr\paperheight-\topskip-\tw@\dimexpr#1\relax\relax/
+ \baselineskip\relax}%
+ \ifx\@jsc@uplatextrue\@undefined\else
+ % the way we found in order for the papersize special written by
+ % geometry in the dvi file to be correct in case of jsbook class
+ \ifnum\mag=\@m\else % do nothing special if nomag class option or 10pt
+ \PassOptionsToPackage{truedimen}{geometry}%
+ \fi
+ \fi
+ \PassOptionsToPackage{%
+ hmarginratio={1:1},%
+ textwidth=\unexpanded{\sphinxtextwidthja{\spx@opt@hmargin}},%
+ vmarginratio={1:1},%
+ lines=\unexpanded{\sphinxtextlinesja{\spx@opt@vmargin}},%
+ marginpar=\unexpanded{\sphinxmarginparwidthja{\spx@opt@marginpar}},%
+ footskip=2\baselineskip,%
+ }{geometry}%
+ \AtBeginDocument
+ {% update a dimension used by the jsclasses
+ \ifx\@jsc@uplatextrue\@undefined\else\fullwidth\textwidth\fi
+ % for some reason, jreport normalizes all dimensions with \@settopoint
+ \@ifclassloaded{jreport}
+ {\@settopoint\textwidth\@settopoint\textheight\@settopoint\marginparwidth}
+ {}% <-- "false" clause of \@ifclassloaded
+ }%
+\fi
+
+\endinput
diff --git a/sphinx/texinputs/sphinxoptionshyperref.sty b/sphinx/texinputs/sphinxoptionshyperref.sty
new file mode 100644
index 0000000000..6017d89704
--- /dev/null
+++ b/sphinx/texinputs/sphinxoptionshyperref.sty
@@ -0,0 +1,35 @@
+%% Bookmarks and hyperlinks
+%
+% change this info string if making any custom modification
+\ProvidesFile{sphinxoptionshyperref.sty}[2021/01/27 hyperref]
+
+% to make pdf with correct encoded bookmarks in Japanese
+% this should precede the hyperref package
+\ifx\kanjiskip\@undefined
+% for non-Japanese: make sure bookmarks are ok also with lualatex
+ \PassOptionsToPackage{pdfencoding=unicode}{hyperref}
+\else
+ \RequirePackage{atbegshi}
+ \ifx\ucs\@undefined
+ \ifnum 42146=\euc"A4A2
+ \AtBeginShipoutFirst{\special{pdf:tounicode EUC-UCS2}}
+ \else
+ \AtBeginShipoutFirst{\special{pdf:tounicode 90ms-RKSJ-UCS2}}
+ \fi
+ \else
+ \AtBeginShipoutFirst{\special{pdf:tounicode UTF8-UCS2}}
+ \fi
+\fi
+
+\ifx\@jsc@uplatextrue\@undefined\else
+ \PassOptionsToPackage{setpagesize=false}{hyperref}
+\fi
+
+% These options can be overriden inside 'hyperref' key
+% or by later use of \hypersetup.
+\PassOptionsToPackage{colorlinks,breaklinks,%
+ linkcolor=InnerLinkColor,filecolor=OuterLinkColor,%
+ menucolor=OuterLinkColor,urlcolor=OuterLinkColor,%
+ citecolor=InnerLinkColor}{hyperref}
+
+\endinput
diff --git a/sphinx/texinputs/sphinxcyrillic.sty b/sphinx/texinputs/sphinxpackagecyrillic.sty
similarity index 98%
rename from sphinx/texinputs/sphinxcyrillic.sty
rename to sphinx/texinputs/sphinxpackagecyrillic.sty
index 6747b5ec64..9aa62fc22b 100644
--- a/sphinx/texinputs/sphinxcyrillic.sty
+++ b/sphinx/texinputs/sphinxpackagecyrillic.sty
@@ -1,7 +1,7 @@
%% CYRILLIC IN NON-CYRILLIC DOCUMENTS (pdflatex only)
%
% refs: https://tex.stackexchange.com/q/460271/
-\ProvidesPackage{sphinxcyrillic}%
+\ProvidesPackage{sphinxpackagecyrillic}%
[2018/11/21 v2.0 support for Cyrillic in non-Cyrillic documents]
\RequirePackage{kvoptions}
\SetupKeyvalOptions{prefix=spx@cyropt@} % use \spx@cyropt@ prefix
diff --git a/sphinx/texinputs/footnotehyper-sphinx.sty b/sphinx/texinputs/sphinxpackagefootnote.sty
similarity index 96%
rename from sphinx/texinputs/footnotehyper-sphinx.sty
rename to sphinx/texinputs/sphinxpackagefootnote.sty
index 3bba385a82..a6071cf103 100644
--- a/sphinx/texinputs/footnotehyper-sphinx.sty
+++ b/sphinx/texinputs/sphinxpackagefootnote.sty
@@ -1,8 +1,13 @@
\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{footnotehyper-sphinx}%
- [2021/02/04 v1.1d hyperref aware footnote.sty for sphinx (JFB)]
+\ProvidesPackage{sphinxpackagefootnote}%
+ [2021/02/04 v1.1d footnotehyper adapted to sphinx (Sphinx team)]
+% Provides support for this output mark-up from Sphinx latex writer:
+% - footnote environment
+% - savenotes environment (table templates)
+% - \sphinxfootnotemark
+%
%%
-%% Package: footnotehyper-sphinx
+%% Package: sphinxpackagefootnote
%% Version: based on footnotehyper.sty 2021/02/04 v1.1d
%% as available at https://www.ctan.org/pkg/footnotehyper
%% License: the one applying to Sphinx
@@ -18,7 +23,7 @@
%% 5. macro definition \sphinxlongtablepatch
%% 6. replaced some \undefined by \@undefined
\newif\iffootnotehyperparse\footnotehyperparsetrue
-\DeclareOption*{\PackageWarning{footnotehyper-sphinx}{Option `\CurrentOption' is unknown}}%
+\DeclareOption*{\PackageWarning{sphinxpackagefootnote}{Option `\CurrentOption' is unknown}}%
\ProcessOptions\relax
\newbox\FNH@notes
\newtoks\FNH@toks % 1.1c
@@ -292,7 +297,7 @@
}%
% slight reformulation for Sphinx
\def\FNH@bad@makefntext@alert{%
- \PackageWarningNoLine{footnotehyper-sphinx}%
+ \PackageWarningNoLine{sphinxpackagefootnote}%
{Footnotes will be sub-optimal, sorry. This is due to the document class or^^J
some package modifying macro \string\@makefntext.^^J
You can try to report this incompatibility at^^J
@@ -322,6 +327,7 @@
\noexpand\if@endpe\noexpand\@endpetrue\noexpand\fi
}%
}%
+%
% some extras for Sphinx :
% \sphinxfootnotemark: usable in section titles and silently removed from TOCs.
\def\sphinxfootnotemark [#1]%
@@ -387,4 +393,4 @@
}%
\endinput
%%
-%% End of file `footnotehyper-sphinx.sty'.
+%% End of file `sphinxpackagefootnote.sty'.
diff --git a/sphinx/themes/agogo/layout.html b/sphinx/themes/agogo/layout.html
index 1d9df693be..855ec8ccb1 100644
--- a/sphinx/themes/agogo/layout.html
+++ b/sphinx/themes/agogo/layout.html
@@ -13,14 +13,14 @@
{% block header %}
{%- for rellink in rellinks|reverse %}
diff --git a/sphinx/themes/basic/globaltoc.html b/sphinx/themes/basic/globaltoc.html
index a47c32cc05..5ac0abbd43 100644
--- a/sphinx/themes/basic/globaltoc.html
+++ b/sphinx/themes/basic/globaltoc.html
@@ -7,5 +7,5 @@
:copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
-
{{ toctree(includehidden=theme_globaltoc_includehidden, collapse=theme_globaltoc_collapse, maxdepth=theme_globaltoc_maxdepth) }}
diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html
index bd56681c00..df07072201 100644
--- a/sphinx/themes/basic/layout.html
+++ b/sphinx/themes/basic/layout.html
@@ -17,9 +17,7 @@
{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %}
{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and
(sidebars != []) %}
-{%- set url_root = pathto('', 1) %}
{# URL root should never be #, then all links are fragments #}
-{%- if url_root == '#' %}{% set url_root = '' %}{% endif %}
{%- if not embedded and docstitle %}
{%- set titlesuffix = " — "|safe + docstitle|e %}
{%- else %}
@@ -37,7 +35,7 @@
{{ _('Navigation') }}
{%- if not loop.first %}{{ reldelim2 }}{% endif %}
{%- endfor %}
{%- block rootrellink %}
-