IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch '5.x' into 10258_autosummary

Browse Source
This commit is contained in:
Takeshi KOMIYA
2022-05-07 21:27:47 +09:00
parent 07b2a050c7 3bc1a33892
commit 5344b1b241
530 changed files with 51642 additions and 53180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.github/workflows/docutils-latest.yml vendored
View File

@@ -7,6 +7,7 @@ on:
jobs:
test:
if: github.repository_owner == 'sphinx-doc'
runs-on: ubuntu-latest
steps:

1
.github/workflows/lock.yml vendored
View File

@@ -10,6 +10,7 @@ permissions:
jobs:
action:
if: github.repository_owner == 'sphinx-doc'
runs-on: ubuntu-latest
steps:
- uses: dessant/lock-threads@v2

80
.github/workflows/main.yml vendored
View File

@@ -5,43 +5,34 @@ on: [push, pull_request]
jobs:
ubuntu:
runs-on: ubuntu-18.04
name: Python ${{ matrix.python }}
strategy:
fail-fast: false
matrix:
name: [py36, py37, py38, py39, py310]
include:
- name: py36
python: 3.6
- python: "3.6"
docutils: du14
- name: py37
python: 3.7
- python: "3.7"
docutils: du15
- name: py38
python: 3.8
- python: "3.8"
docutils: du16
- name: py39
python: 3.9
- python: "3.9"
docutils: du17
coverage: "--cov ./ --cov-append --cov-config setup.cfg"
- name: py310
python: "3.10"
docutils: du17
- name: py311-dev
python: 3.11-dev
- python: "3.10"
docutils: du18
- python: "3.11-dev"
docutils: py311
env:
PYTEST_ADDOPTS: ${{ matrix.coverage }}
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python }}
uses: actions/setup-python@v2
uses: actions/setup-python@v3
if: "!endsWith(matrix.python, '-dev')"
with:
python-version: ${{ matrix.python }}
- name: Set up Python ${{ matrix.python }} (deadsnakes)
uses: deadsnakes/action@v2.0.1
if: endsWith(matrix.python, '-dev')
if: "endsWith(matrix.python, '-dev')"
with:
python-version: ${{ matrix.python }}
- name: Check Python version
@@ -49,29 +40,48 @@ jobs:
- name: Install graphviz
run: sudo apt-get install graphviz
- name: Install dependencies
run: pip install -U tox codecov
- name: Install the latest py package (for py3.11-dev)
run: pip install -U git+https://github.com/pytest-dev/py
if: ${{ matrix.python == '3.11-dev' }}
run: python -m pip install -U pip tox
- name: Run Tox
run: tox -e ${{ matrix.docutils }} -- -vv
- name: codecov
uses: codecov/codecov-action@v1
if: matrix.coverage
windows:
runs-on: windows-2019
strategy:
matrix:
architecture: [x86, x64]
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v1
uses: actions/setup-python@v3
with:
architecture: ${{ matrix.architecture }}
python-version: 3
- name: Install dependencies
run: pip install -U tox
run: python -m pip install -U pip tox
- name: Run Tox
run: tox -e py -- -vv
coverage:
# only run on pushes to branches in the sphinx-doc/sphinx repo
if: github.repository_owner == 'sphinx-doc' && github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python 3
uses: actions/setup-python@v3
with:
python-version: 3
- name: Check Python version
run: python --version
- name: Install graphviz
run: sudo apt-get install graphviz
- name: Install dependencies
run: python -m pip install -U pip tox pytest-cov
- name: Run Tox
run: tox --sitepackages -e py -- -vv
env:
PYTEST_ADDOPTS: "--cov ./ --cov-append --cov-config setup.cfg"
- name: codecov
uses: codecov/codecov-action@v3

16
.github/workflows/transifex.yml vendored
View File

@@ -7,46 +7,52 @@ on:
jobs:
push:
if: github.repository_owner == 'sphinx-doc'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
ref: 4.x
ref: 5.x
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: 3.9 # https://github.com/transifex/transifex-client/pull/330
- name: Install dependencies
run: pip install -U babel jinja2 transifex-client
- name: Install Sphinx
run: pip install .
- name: Extract translations from source code
run: python setup.py extract_messages
run: python utils/babel_runner.py extract
- name: Push translations to transifex.com
run: cd sphinx/locale && tx push -s --no-interactive --parallel
env:
TX_TOKEN: ${{ secrets.TX_TOKEN }}
pull:
if: github.repository_owner == 'sphinx-doc'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
ref: 4.x
ref: 5.x
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: 3.9 # https://github.com/transifex/transifex-client/pull/330
- name: Install dependencies
run: pip install -U babel jinja2 transifex-client
- name: Install Sphinx
run: pip install .
- name: Extract translations from source code
run: python setup.py extract_messages
run: python utils/babel_runner.py extract
- name: Pull translations to transifex.com
run: cd sphinx/locale && tx pull -a -f --no-interactive --parallel
env:
TX_TOKEN: ${{ secrets.TX_TOKEN }}
- name: Compile message catalogs
run: python setup.py compile_catalog
run: python utils/babel_runner.py compile
- name: Create Pull Request
uses: peter-evans/create-pull-request@v3
with:

1
AUTHORS
View File

@@ -74,6 +74,7 @@ Other contributors, listed alphabetically, are:
* Pauli Virtanen -- autodoc improvements, autosummary extension
* Eric N. Vander Weele -- autodoc improvements
* Stefan van der Walt -- autosummary extension
* Hugo van Kemenade -- support FORCE_COLOR and NO_COLOR
* Thomas Waldmann -- apidoc module fixes
* John Waltman -- Texinfo builder
* Barry Warsaw -- setup command improvements

101
CHANGES
View File

@@ -3,6 +3,9 @@ Release 5.0.0 (in development)
Dependencies
------------
* #10164: Support `Docutils 0.18`_. Patch by Adam Turner.
.. _Docutils 0.18: https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-18-2021-10-26
Incompatible changes
--------------------
@@ -50,6 +53,9 @@ Deprecated
required
* The ``language`` argument of ``sphinx.util.i18n:format_date()`` becomes
required
* ``sphinx.builders.html.html5_ready``
* ``sphinx.util.docutils.__version_info__``
* ``sphinx.util.docutils.is_html5_writer_available()``
* ``sphinx.writers.latex.LaTeXWriter.docclasses``
Features added
@@ -58,23 +64,50 @@ Features added
* #9075: autodoc: The default value of :confval:`autodoc_typehints_format` is
changed to ``'smart'``. It will suppress the leading module names of
typehints (ex. ``io.StringIO`` -> ``StringIO``).
* #8417: autodoc: ``:inherited-members:`` option now takes multiple classes. It
allows to suppress inherited members of several classes on the module at once
by specifying the option to :rst:dir:`automodule` directive
* #9792: autodoc: Add new option for ``autodoc_typehints_description_target`` to
include undocumented return values but not undocumented parameters.
* #10285: autodoc: singledispatch functions having typehints are not documented
* #10028: Removed internal usages of JavaScript frameworks (jQuery and
underscore.js) and modernised ``doctools.js`` and ``searchtools.js`` to
EMCAScript 2018.
* #10302: C++, add support for conditional expressions (``?:``).
* #5157, #10251: Inline code is able to be highlighted via :rst:dir:`role`
directive
Bugs fixed
----------
* #10200: apidoc: Duplicated submodules are shown for modules having both .pyx
and .so files
* #10279: autodoc: Default values for keyword only arguments in overloaded
functions are rendered as a string literal
* #10280: autodoc: :confval:`autodoc_docstring_signature` unexpectedly generates
return value typehint for constructors if docstring has multiple signatures
* #10266: autodoc: :confval:`autodoc_preserve_defaults` does not work for
mixture of keyword only arguments with/without defaults
* #10310: autodoc: class methods are not documented when decorated with mocked
function
* #10305: autodoc: Failed to extract optional forward-ref'ed typehints correctly
via :confval:`autodoc_type_aliases`
* #10214: html: invalid language tag was generated if :confval:`language`
contains a country code (ex. zh_CN)
* #10236: html search: objects are duplicated in search result
* #9962: texinfo: Deprecation message for ``@definfoenclose`` command on
bulding texinfo document
* #10000: LaTeX: glossary terms with common definition are rendered with
too much vertical whitespace
* #10188: LaTeX: alternating multiply referred footnotes produce a ``?`` in
pdf output
* #10318: ``:prepend:`` option of :rst:dir:`literalinclude` directive does not
work with ``:dedent:`` option
Testing
--------
Release 4.5.0 (in development)
Release 4.5.1 (in development)
==============================
Dependencies
@@ -86,26 +119,60 @@ Incompatible changes
Deprecated
----------
Features added
--------------
Bugs fixed
----------
Testing
--------
Release 4.5.0 (released Mar 28, 2022)
=====================================
Incompatible changes
--------------------
* #10112: extlinks: Disable hardcoded links detector by default
* #9993, #10177: std domain: Disallow to refer an inline target via
:rst:role:`ref` role
Deprecated
----------
* ``sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()``
Features added
--------------
* #10260: Enable ``FORCE_COLOR`` and ``NO_COLOR`` for terminal colouring
* #10234: autosummary: Add "autosummary" CSS class to summary tables
* #10125: extlinks: Improve suggestion message for a reference having title
* #10112: extlinks: Add :confval:`extlinks_detect_hardcoded_links` to enable
hardcoded links detector feature
* #9494, #9456: html search: Add a config variable
:confval:`html_show_search_summary` to enable/disable the search summaries
* #9337: HTML theme, add option ``enable_search_shortcuts`` that enables :kbd:'/' as
* #9337: HTML theme, add option ``enable_search_shortcuts`` that enables :kbd:`/` as
a Quick search shortcut and :kbd:`Esc` shortcut that
removes search highlighting.
* #10107: i18n: Allow to suppress translation warnings by adding ``#noqa``
comment to the tail of each translation message
* #10252: C++, support attributes on classes, unions, and enums.
* #10253: :rst:dir:`pep` role now generates URLs based on peps.python.org
Bugs fixed
----------
* #9876: autodoc: Failed to document an imported class that is built from native
binary module
* #10133: autodoc: Crashed when mocked module is used for type annotation
* #10146: autodoc: :confval:`autodoc_default_options` does not support
``no-value`` option
* #9971: autodoc: TypeError is raised when the target object is annotated by
unhashable object
* #10205: extlinks: Failed to compile regexp on checking hardcoded links
* #10277: html search: Could not search short words (ex. "use")
* #9529: LaTeX: named auto numbered footnote (ex. ``[#named]``) that is referred
multiple times was rendered to a question mark
* #9924: LaTeX: multi-line :rst:dir:`cpp:function` directive has big vertical
@@ -114,38 +181,14 @@ Bugs fixed
variables/structure members
* #10175: LaTeX: named footnote reference is linked to an incorrect footnote if
the name is also used in the different document
* #10269: manpage: Failed to resolve the title of :ref: cross references
* #10179: i18n: suppress "rST localization" warning
* #10118: imgconverter: Unnecessary availablity check is called for remote URIs
* #10181: napoleon: attributes are displayed like class attributes for google
style docstrings when :confval:`napoleon_use_ivar` is enabled
* #10122: sphinx-build: make.bat does not check the installation of sphinx-build
command before showing help
Testing
--------
Release 4.4.1 (in development)
==============================
Dependencies
------------
Incompatible changes
--------------------
Deprecated
----------
Features added
--------------
Bugs fixed
----------
* #9876: autodoc: Failed to document an imported class that is built from native
binary module
Testing
--------
Release 4.4.0 (released Jan 17, 2022)
=====================================

3
LICENSE
View File

@@ -1,6 +1,9 @@
License for Sphinx
==================
Unless otherwise indicated, all code in the Sphinx project is licenced under the
two clause BSD licence below.
Copyright (c) 2007-2022 by the Sphinx team (see AUTHORS file).
All rights reserved.

4
Makefile
View File

@@ -66,11 +66,11 @@ doclinter:
.PHONY: test
test:
@$(PYTHON) -X dev -m pytest -v $(TEST)
@$(PYTHON) -X dev -X warn_default_encoding -m pytest -v $(TEST)
.PHONY: covertest
covertest:
@$(PYTHON) -X dev -m pytest -v --cov=sphinx --junitxml=.junit.xml $(TEST)
@$(PYTHON) -X dev -X warn_default_encoding -m pytest -v --cov=sphinx --junitxml=.junit.xml $(TEST)
.PHONY: build
build:

6
doc/conf.py
View File

@@ -109,7 +109,7 @@ texinfo_documents = [
intersphinx_mapping = {
'python': ('https://docs.python.org/3/', None),
'requests': ('https://requests.readthedocs.io/en/master', None),
'requests': ('https://docs.python-requests.org/en/latest/', None),
'readthedocs': ('https://docs.readthedocs.io/en/stable', None),
}
@@ -148,9 +148,9 @@ def linkify_issues_in_changelog(app, docname, source):
# this path trickery is needed because this script can
# be invoked with different working directories:
# * running make in docs/
# * running python setup.py build_sphinx in the repo root dir
# * running tox -e docs in the repo root dir
with open(changelog_path) as f:
with open(changelog_path, encoding="utf-8") as f:
changelog = f.read()
def linkify(match):

2
doc/development/theming.rst
View File

@@ -265,7 +265,7 @@ Here is some sample code to accomplish this:
copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
def setup(app):
app.connect('builder-inited', copy_custom_files)
app.connect('build-finished', copy_custom_files)
Inject JavaScript based on user configuration

8
doc/development/tutorials/examples/todo.py
View File

@@ -70,7 +70,7 @@ def merge_todos(app, env, docnames, other):
def process_todo_nodes(app, doctree, fromdocname):
if not app.config.todo_include_todos:
for node in doctree.traverse(todo):
for node in doctree.findall(todo):
node.parent.remove(node)
# Replace all todolist nodes with a list of the collected todos.
@@ -80,7 +80,7 @@ def process_todo_nodes(app, doctree, fromdocname):
if not hasattr(env, 'todo_all_todos'):
env.todo_all_todos = []
for node in doctree.traverse(todolist):
for node in doctree.findall(todolist):
if not app.config.todo_include_todos:
node.replace_self([])
continue
@@ -93,7 +93,7 @@ def process_todo_nodes(app, doctree, fromdocname):
description = (
_('(The original entry is located in %s, line %d and can be found ') %
(filename, todo_info['lineno']))
para += nodes.Text(description, description)
para += nodes.Text(description)
# Create a reference
newnode = nodes.reference('', '')
@@ -104,7 +104,7 @@ def process_todo_nodes(app, doctree, fromdocname):
newnode['refuri'] += '#' + todo_info['target']['refid']
newnode.append(innernode)
para += newnode
para += nodes.Text('.)', '.)')
para += nodes.Text('.)')
# Insert into the todolist
content.append(todo_info['todo'])

20
doc/extdev/deprecated.rst
View File

@@ -22,6 +22,11 @@ The following is a list of deprecated interfaces.
- (will be) Removed
- Alternatives
* - ``sphinx.util.jsdump``
- 5.0
- 7.0
- The standard library ``json`` module.
* - :doc:`Setuptools integration </usage/advanced/setuptools>`
- 5.0
- 7.0
@@ -37,6 +42,21 @@ The following is a list of deprecated interfaces.
- 7.0
- N/A
* - ``sphinx.builders.html.html5_ready``
- 5.0
- 7.0
- N/A
* - ``sphinx.util.docutils.__version_info__``
- 5.0
- 7.0
- ``docutils.__version_info__``
* - ``sphinx.util.docutils.is_html5_writer_available()``
- 5.0
- 7.0
- N/A
* - ``sphinx.writers.latex.LaTeXWriter.docclasses``
- 5.0
- 7.0

2
doc/extdev/index.rst
View File

@@ -178,7 +178,7 @@ as metadata of the extension. Metadata keys currently recognized are:
* The core logic of the extension is parallelly executable during
the reading phase.
* It has event handlers for :event:`env-merge-info` and
:event:`env-purge-doc` events if it stores dataa to the build
:event:`env-purge-doc` events if it stores data to the build
environment object (env) during the reading phase.
* ``'parallel_write_safe'``: a boolean that specifies if parallel writing of

1
doc/extdev/parserapi.rst
View File

@@ -35,3 +35,4 @@ to configure their settings appropriately.
.. module:: sphinx.parsers
.. autoclass:: Parser
:members:

20
doc/internals/contributing.rst
View File

@@ -252,17 +252,19 @@ locales. The translations are kept as gettext ``.po`` files translated from the
master template :file:`sphinx/locale/sphinx.pot`.
Sphinx uses `Babel <https://babel.pocoo.org/en/latest/>`_ to extract messages
and maintain the catalog files. It is integrated in ``setup.py``:
and maintain the catalog files. The ``utils`` directory contains a helper
script, ``babel_runner.py``.
* Use ``python setup.py extract_messages`` to update the ``.pot`` template.
* Use ``python setup.py update_catalog`` to update all existing language
* Use ``python babel_runner.py extract`` to update the ``.pot`` template.
* Use ``python babel_runner.py update`` to update all existing language
catalogs in ``sphinx/locale/*/LC_MESSAGES`` with the current messages in the
template file.
* Use ``python setup.py compile_catalog`` to compile the ``.po`` files to binary
* Use ``python babel_runner.py compile`` to compile the ``.po`` files to binary
``.mo`` files and ``.js`` files.
When an updated ``.po`` file is submitted, run compile_catalog to commit both
the source and the compiled catalogs.
When an updated ``.po`` file is submitted, run
``python babel_runner.py compile`` to commit both the source and the compiled
catalogs.
When a new locale is submitted, add a new directory with the ISO 639-1 language
identifier and put ``sphinx.po`` in there. Don't forget to update the possible
@@ -273,9 +275,9 @@ The Sphinx core messages can also be translated on `Transifex
which is provided by the ``transifex_client`` Python package, can be used to
pull translations in ``.po`` format from Transifex. To do this, go to
``sphinx/locale`` and then run ``tx pull -f -l LANG`` where ``LANG`` is an
existing language identifier. It is good practice to run ``python setup.py
update_catalog`` afterwards to make sure the ``.po`` file has the canonical
Babel formatting.
existing language identifier. It is good practice to run
``python babel_runner.py update`` afterwards to make sure the ``.po`` file has the
canonical Babel formatting.
Debugging tips

16
doc/man/sphinx-build.rst
View File

@@ -304,6 +304,22 @@ variables to customize behavior:
Additional options for :program:`sphinx-build`. These options can
also be set via the shortcut variable **O** (capital 'o').
.. describe:: NO_COLOR
When set (regardless of value), :program:`sphinx-build` will not use color
in terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``. See
`no-color.org <https://no-color.org/>`__ for other libraries supporting this
community standard.
.. versionadded:: 4.5.0
.. describe:: FORCE_COLOR
When set (regardless of value), :program:`sphinx-build` will use color in
terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``.
.. versionadded:: 4.5.0
.. _when-deprecation-warnings-are-displayed:
Deprecation Warnings

7
doc/tutorial/automatic-doc-generation.rst
View File

@@ -4,10 +4,9 @@ Automatic documentation generation from code
In the :ref:`previous section <tutorial-describing-objects>` of the tutorial
you manually documented a Python function in Sphinx. However, the description
was out of sync with the code itself, since the function signature was not
the same. Besides, it would be nice to reuse `Python
docstrings <https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring>`_
in the documentation, rather than having to write the information in two
places.
the same. Besides, it would be nice to reuse :pep:`Python docstrings
<257#what-is-a-docstring>` in the documentation, rather than having to write
the information in two places.
Fortunately, :doc:`the autodoc extension </usage/extensions/autodoc>` provides this
functionality.

18
doc/usage/advanced/intl.rst
View File

@@ -68,6 +68,24 @@ be translated you need to follow these instructions:
* Run your desired build.
In order to protect against mistakes, a warning is emitted if
cross-references in the translated paragraph do not match those from the
original. This can be turned off globally using the
:confval:`suppress_warnings` configuration variable. Alternatively, to
turn it off for one message only, end the message with ``#noqa`` like
this::
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa
(Write ``\#noqa`` in case you want to have "#noqa" literally in the
text. This does not apply to code blocks, where ``#noqa`` is ignored
because code blocks do not contain references anyway.)
.. versionadded:: 4.5
The ``#noqa`` mechanism.
Translating with sphinx-intl
----------------------------

16
doc/usage/configuration.rst
View File

@@ -316,7 +316,11 @@ General configuration
* ``app.add_role``
* ``app.add_generic_role``
* ``app.add_source_parser``
* ``autosectionlabel.*``
* ``download.not_readable``
* ``epub.unknown_project_files``
* ``epub.duplicated_toc_entry``
* ``i18n.inconsistent_references``
* ``image.not_readable``
* ``ref.term``
* ``ref.ref``
@@ -332,11 +336,9 @@ General configuration
* ``toc.excluded``
* ``toc.not_readable``
* ``toc.secnum``
* ``epub.unknown_project_files``
* ``epub.duplicated_toc_entry``
* ``autosectionlabel.*``
You can choose from these types.
You can choose from these types. You can also give only the first
component to exclude all warnings attached to it.
Now, this option should be considered *experimental*.
@@ -366,6 +368,10 @@ General configuration
Added ``toc.excluded`` and ``toc.not_readable``
.. versionadded:: 4.5
Added ``i18n.inconsistent_references``
.. confval:: needs_sphinx
If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
@@ -546,7 +552,7 @@ General configuration
make latex O="-D smartquotes_action="
This can follow some ``make html`` with no problem, in contrast to the
situation from the prior note. It requires Docutils 0.14 or later.
situation from the prior note.
.. versionadded:: 1.6.6

21
doc/usage/extensions/autodoc.rst
View File

@@ -266,6 +266,10 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
``__str__`` will be documented as in the past, but other special method
that are not implemented in your class ``Foo``.
Since v5.0, it can take a comma separated list of ancestor classes. It
allows to suppress inherited members of several classes on the module at
once by specifying the option to :rst:dir:`automodule` directive.
Note: this will lead to markup errors if the inherited members come from a
module whose docstrings are not reST formatted.
@@ -275,6 +279,10 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
It takes an ancestor class name as an argument.
.. versionchanged:: 5.0
It takes a comma separated list of ancestor class names.
* It's possible to override the signature for explicitly documented callable
objects (functions, methods, classes) with the regular syntax that will
override the signature gained from introspection::
@@ -626,16 +634,24 @@ There are also config values that you can set:
When set to ``"documented"``, types will only be documented for a parameter
or a return value that is already documented by the docstring.
With ``"documented_params"``, parameter types will only be annotated if the
parameter is documented in the docstring. The return type is always
annotated (except if it is ``None``).
.. versionadded:: 4.0
.. versionadded:: 5.0
New option ``'documented_params'`` is added.
.. confval:: autodoc_type_aliases
A dictionary for users defined `type aliases`__ that maps a type name to the
full-qualified object name. It is used to keep type aliases not evaluated in
the document. Defaults to empty (``{}``).
The type aliases are only available if your program enables `Postponed
Evaluation of Annotations (PEP 563)`__ feature via ``from __future__ import
The type aliases are only available if your program enables :pep:`Postponed
Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import
annotations``.
For example, there is code using a type alias::
@@ -662,7 +678,6 @@ There are also config values that you can set:
...
.. __: https://www.python.org/dev/peps/pep-0563/
.. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
.. versionadded:: 3.3

4
doc/usage/extensions/doctest.rst
View File

@@ -93,8 +93,8 @@ a comma-separated list of group names.
* ``<``, ``>``: Exclusive ordered comparison clause
* ``===``: Arbitrary equality clause.
``pyversion`` option is followed `PEP-440: Version Specifiers
<https://www.python.org/dev/peps/pep-0440/#version-specifiers>`__.
``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
<440#version-specifiers>`.
.. versionadded:: 1.6

8
doc/usage/extensions/example_google.py
View File

@@ -45,7 +45,7 @@ on the first line, separated by a colon.
def function_with_types_in_docstring(param1, param2):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
:pep:`484` type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
@@ -55,10 +55,6 @@ def function_with_types_in_docstring(param1, param2):
Returns:
bool: The return value. True for success, False otherwise.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
"""
@@ -311,4 +307,4 @@ class ExamplePEP526Class:
"""
attr1: str
attr2: int
attr2: int

6
doc/usage/extensions/example_numpy.py
View File

@@ -55,7 +55,7 @@ on the first line, separated by a colon.
def function_with_types_in_docstring(param1, param2):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
:pep:`484` type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
@@ -70,10 +70,6 @@ def function_with_types_in_docstring(param1, param2):
-------
bool
True if successful, False otherwise.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
"""

8
doc/usage/extensions/extlinks.rst
View File

@@ -59,3 +59,11 @@ The extension adds a config value:
Since links are generated from the role in the reading stage, they appear as
ordinary links to e.g. the ``linkcheck`` builder.
.. confval:: extlinks_detect_hardcoded_links
If enabled, extlinks emits a warning if a hardcoded link is replaceable
by an extlink, and suggests a replacement via warning. It defaults to
``False``.
.. versionadded:: 4.5

19
doc/usage/extensions/napoleon.rst
View File

@@ -26,7 +26,7 @@ Are you tired of writing docstrings that look like this::
:rtype: BufferedFileStorage
`reStructuredText`_ is great, but it creates visually dense, hard to read
`docstrings`_. Compare the jumble above to the same thing rewritten
:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten
according to the `Google Python Style Guide`_::
Args:
@@ -50,11 +50,10 @@ the documentation, so it doesn't modify any of the docstrings in your actual
source code files.
.. _ReStructuredText: https://docutils.sourceforge.io/rst.html
.. _docstrings: https://www.python.org/dev/peps/pep-0287/
.. _Google Python Style Guide:
https://google.github.io/styleguide/pyguide.html
.. _Google:
https://google.github.io/styleguide/pyguide.html#Comments
https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
.. _NumPy:
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
.. _Khan Academy:
@@ -199,11 +198,11 @@ not be mixed. Choose one style for your project and be consistent with it.
Type Annotations
~~~~~~~~~~~~~~~~
`PEP 484`_ introduced a standard way to express types in Python code.
:pep:`484` introduced a standard way to express types in Python code.
This is an alternative to expressing types directly in docstrings.
One benefit of expressing types according to `PEP 484`_ is that
One benefit of expressing types according to :pep:`484` is that
type checkers and IDEs can take advantage of them for static code
analysis. `PEP 484`_ was then extended by `PEP 526`_ which introduced
analysis. :pep:`484` was then extended by :pep:`526` which introduced
a similar way to annotate variables (and attributes).
Google style with Python 3 type annotations::
@@ -267,9 +266,7 @@ Google style with types in docstrings::
`Python 2/3 compatible annotations`_ aren't currently
supported by Sphinx and won't show up in the docs.
.. _PEP 484: https://www.python.org/dev/peps/pep-0484/
.. _PEP 526: https://www.python.org/dev/peps/pep-0526/
.. _Python 2/3 compatible annotations: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
.. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
Configuration
@@ -301,7 +298,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
napoleon_attr_annotations = True
.. _Google style:
https://google.github.io/styleguide/pyguide.html
https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
.. _NumPy style:
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
@@ -548,7 +545,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
.. confval:: napoleon_attr_annotations
True to allow using `PEP 526`_ attributes annotations in classes.
True to allow using :pep:`526` attributes annotations in classes.
If an attribute is documented in the docstring without a type and
has an annotation in the class body, that type is used.

6
doc/usage/restructuredtext/directives.rst
View File

@@ -499,8 +499,10 @@ __ https://pygments.org/docs/lexers
The directive's alias name :rst:dir:`sourcecode` works as well. This
directive takes a language name as an argument. It can be `any lexer alias
supported by Pygments <https://pygments.org/docs/lexers/>`_. If it is not
given, the setting of :rst:dir:`highlight` directive will be used.
If not set, :confval:`highlight_language` will be used.
given, the setting of :rst:dir:`highlight` directive will be used. If not
set, :confval:`highlight_language` will be used. To display a code example
*inline* within other text, rather than as a separate block, you can use the
:rst:role:`code` role instead.
.. versionchanged:: 2.0
The ``language`` argument becomes optional.

42
doc/usage/restructuredtext/domains.rst
View File

@@ -211,6 +211,12 @@ The following directives are provided for module and class contents:
.. versionadded:: 4.0
.. rst::directive:option:: module
:type: text
Describe the location where the object is defined. The default value is
the module specified by :rst:dir:`py:currentmodule`.
.. rst:directive:: .. py:data:: name
Describes global data in a module, including both variables and values used
@@ -237,6 +243,12 @@ The following directives are provided for module and class contents:
.. versionadded:: 4.0
.. rst::directive:option:: module
:type: text
Describe the location where the object is defined. The default value is
the module specified by :rst:dir:`py:currentmodule`.
.. rst:directive:: .. py:exception:: name
Describes an exception class. The signature can, but need not include
@@ -251,6 +263,12 @@ The following directives are provided for module and class contents:
.. versionadded:: 3.1
.. rst::directive:option:: module
:type: text
Describe the location where the object is defined. The default value is
the module specified by :rst:dir:`py:currentmodule`.
.. rst:directive:: .. py:class:: name
.. py:class:: name(parameters)
@@ -291,6 +309,12 @@ The following directives are provided for module and class contents:
.. versionadded:: 3.1
.. rst::directive:option:: module
:type: text
Describe the location where the object is defined. The default value is
the module specified by :rst:dir:`py:currentmodule`.
.. rst:directive:: .. py:attribute:: name
Describes an object data attribute. The description should include
@@ -317,6 +341,12 @@ The following directives are provided for module and class contents:
.. versionadded:: 4.0
.. rst::directive:option:: module
:type: text
Describe the location where the object is defined. The default value is
the module specified by :rst:dir:`py:currentmodule`.
.. rst:directive:: .. py:property:: name
Describes an object property.
@@ -340,6 +370,12 @@ The following directives are provided for module and class contents:
.. rst:directive:option:: type: type of the property
:type: text
.. rst::directive:option:: module
:type: text
Describe the location where the object is defined. The default value is
the module specified by :rst:dir:`py:currentmodule`.
.. rst:directive:: .. py:method:: name(parameters)
Describes an object method. The parameters should not include the ``self``
@@ -385,6 +421,12 @@ The following directives are provided for module and class contents:
.. versionadded:: 3.1
.. rst::directive:option:: module
:type: text
Describe the location where the object is defined. The default value is
the module specified by :rst:dir:`py:currentmodule`.
.. rst:directive:option:: property
:type: no value

28
doc/usage/restructuredtext/roles.rst
View File

@@ -276,6 +276,34 @@ The following role creates a cross-reference to a term in a
If you use a term that's not explained in a glossary, you'll get a warning
during build.
Inline code highlighting
------------------------
.. rst:role:: code
An *inline* code example. When used directly, this role just displays the
text *without* syntax highlighting, as a literal.
.. code-block:: rst
By default, inline code such as :code:`1 + 2` just displays without
highlighting.
Unlike the :rst:dir:`code-block` directive, this role does not respect the
default language set by the :rst:dir:`highlight` directive.
To enable syntax highlighting, you must first use the ``role`` directive to
define a custom ``code`` role for a particular language:
.. code-block:: rst
.. role:: python(code)
:language: python
In Python, :python:`1 + 2` is equal to :python:`3`.
To display a multi-line code example, use the :rst:dir:`code-block` directive
instead.
Math
----

86
package-lock.json generated
View File

@@ -1510,9 +1510,9 @@
"dev": true
},
"@types/node": {
"version": "17.0.17",
"resolved": "https://registry.npmjs.org/@types/node/-/node-17.0.17.tgz",
"integrity": "sha512-e8PUNQy1HgJGV3iU/Bp2+D/DXh3PYeyli8LgIwsQcs1Ar1LoaWHSIT6Rw+H2rNJmiq6SNWiDytfx8+gYj7wDHw==",
"version": "17.0.21",
"resolved": "https://registry.npmjs.org/@types/node/-/node-17.0.21.tgz",
"integrity": "sha512-DBZCJbhII3r90XbQxI8Y9IjjiiOGlZ0Hr32omXIZvwwZ7p4DMMXGrKXVyPfuoBOri9XNtL0UK69jYIBIsRX3QQ==",
"dev": true
},
"accepts": {
@@ -1575,20 +1575,20 @@
"dev": true
},
"body-parser": {
"version": "1.19.1",
"resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.19.1.tgz",
"integrity": "sha512-8ljfQi5eBk8EJfECMrgqNGWPEY5jWP+1IzkzkGdFFEwFQZZyaZ21UqdaHktgiMlH0xLHqIFtE/u2OYE5dOtViA==",
"version": "1.19.2",
"resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.19.2.tgz",
"integrity": "sha512-SAAwOxgoCKMGs9uUAUFHygfLAyaniaoun6I8mFY9pRAJL9+Kec34aU+oIjDhTycub1jozEfEwx1W1IuOYxVSFw==",
"dev": true,
"requires": {
"bytes": "3.1.1",
"bytes": "3.1.2",
"content-type": "~1.0.4",
"debug": "2.6.9",
"depd": "~1.1.2",
"http-errors": "1.8.1",
"iconv-lite": "0.4.24",
"on-finished": "~2.3.0",
"qs": "6.9.6",
"raw-body": "2.4.2",
"qs": "6.9.7",
"raw-body": "2.4.3",
"type-is": "~1.6.18"
}
},
@@ -1612,9 +1612,9 @@
}
},
"bytes": {
"version": "3.1.1",
"resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.1.tgz",
"integrity": "sha512-dWe4nWO/ruEOY7HkUJ5gFt1DCFV9zPRoJr8pV0/ASQermOZjtq8jMjOprC0Kd10GLN+l7xaUPvxzJFWtxGu8Fg==",
"version": "3.1.2",
"resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
"integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
"dev": true
},
"chokidar": {
@@ -1775,9 +1775,9 @@
"dev": true
},
"engine.io": {
"version": "6.1.2",
"resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.1.2.tgz",
"integrity": "sha512-v/7eGHxPvO2AWsksyx2PUsQvBafuvqs0jJJQ0FdmJG1b9qIvgSbqDRGwNhfk2XHaTTbTXiC4quRE8Q9nRjsrQQ==",
"version": "6.1.3",
"resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.1.3.tgz",
"integrity": "sha512-rqs60YwkvWTLLnfazqgZqLa/aKo+9cueVfEi/dZ8PyGyaf8TLOxj++4QMIgeG3Gn0AhrWiFXvghsoY9L9h25GA==",
"dev": true,
"requires": {
"@types/cookie": "^0.4.1",
@@ -1788,7 +1788,7 @@
"cookie": "~0.4.1",
"cors": "~2.8.5",
"debug": "~4.3.1",
"engine.io-parser": "~5.0.0",
"engine.io-parser": "~5.0.3",
"ws": "~8.2.3"
},
"dependencies": {
@@ -1879,15 +1879,15 @@
"dev": true
},
"follow-redirects": {
"version": "1.14.8",
"resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.14.8.tgz",
"integrity": "sha512-1x0S9UVJHsQprFcEC/qnNzBLcIxsjAV905f/UkQxbclCsoTWlacCNOpQa/anodLl2uaEKFhfWOvM2Qg77+15zA==",
"version": "1.14.9",
"resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.14.9.tgz",
"integrity": "sha512-MQDfihBQYMcyy5dhRDJUHcw7lb2Pv/TuE6xP1vyraLukNDHKbDxDNaOE3NbCAdKQApno+GPRyo1YAp89yCjK4w==",
"dev": true
},
"fs-extra": {
"version": "10.0.0",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.0.0.tgz",
"integrity": "sha512-C5owb14u9eJwizKGdchcDUQeFtlSHHthBk8pbX9Vc1PFZrLombudjDnNns88aYslCyF6IY5SUw3Roz6xShcEIQ==",
"version": "10.0.1",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.0.1.tgz",
"integrity": "sha512-NbdoVMZso2Lsrn/QwLXOy6rm0ufY2zEOKCDzJR/0kBsb0E6qed0P3iYK+Ath3BfvXEeu4JhEtXLgILx5psUfag==",
"dev": true,
"requires": {
"graceful-fs": "^4.2.0",
@@ -2072,9 +2072,9 @@
}
},
"karma": {
"version": "6.3.14",
"resolved": "https://registry.npmjs.org/karma/-/karma-6.3.14.tgz",
"integrity": "sha512-SDFoU5F4LdosEiUVWUDRPCV/C1zQRNtIakx7rWkigf7R4sxGADlSEeOma4S1f/js7YAzvqLW92ByoiQptg+8oQ==",
"version": "6.3.16",
"resolved": "https://registry.npmjs.org/karma/-/karma-6.3.16.tgz",
"integrity": "sha512-nEU50jLvDe5yvXqkEJRf8IuvddUkOY2x5Xc4WXHz6dxINgGDrgD2uqQWeVrJs4hbfNaotn+HQ1LZJ4yOXrL7xQ==",
"dev": true,
"requires": {
"body-parser": "^1.19.0",
@@ -2092,6 +2092,7 @@
"log4js": "^6.4.1",
"mime": "^2.5.2",
"minimatch": "^3.0.4",
"mkdirp": "^0.5.5",
"qjobs": "^1.2.0",
"range-parser": "^1.2.1",
"rimraf": "^3.0.2",
@@ -2185,14 +2186,29 @@
}
},
"minimatch": {
"version": "3.0.5",
"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.5.tgz",
"integrity": "sha512-tUpxzX0VAzJHjLu0xUfFv1gwVp9ba3IOuRAVH2EGuRW8a5emA2FlACLqiT/lDVtS1W+TGNwqz3sWaNyLgDJWuw==",
"version": "3.1.2",
"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
"integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
"dev": true,
"requires": {
"brace-expansion": "^1.1.7"
}
},
"minimist": {
"version": "1.2.6",
"resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.6.tgz",
"integrity": "sha512-Jsjnk4bw3YJqYzbdyBiNsPWHPfO++UGG749Cxs6peCu5Xg4nrena6OVxOYxrQTqww0Jmwt+Ref8rggumkTLz9Q==",
"dev": true
},
"mkdirp": {
"version": "0.5.5",
"resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.5.tgz",
"integrity": "sha512-NKmAlESf6jMGym1++R0Ra7wvhV+wFW63FaSOFPwRahvea0gMUcGUhVeAg/0BC0wiv9ih5NYPB1Wn1UEI1/L+xQ==",
"dev": true,
"requires": {
"minimist": "^1.2.5"
}
},
"ms": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz",
@@ -2260,9 +2276,9 @@
"dev": true
},
"qs": {
"version": "6.9.6",
"resolved": "https://registry.npmjs.org/qs/-/qs-6.9.6.tgz",
"integrity": "sha512-TIRk4aqYLNoJUbd+g2lEdz5kLWIuTMRagAXxl78Q0RiVjAOugHmeKNGdd3cwo/ktpf9aL9epCfFqWDEKysUlLQ==",
"version": "6.9.7",
"resolved": "https://registry.npmjs.org/qs/-/qs-6.9.7.tgz",
"integrity": "sha512-IhMFgUmuNpyRfxA90umL7ByLlgRXu6tIfKPpF5TmcfRLlLCckfP/g3IQmju6jjpu+Hh8rA+2p6A27ZSPOOHdKw==",
"dev": true
},
"range-parser": {
@@ -2272,12 +2288,12 @@
"dev": true
},
"raw-body": {
"version": "2.4.2",
"resolved": "https://registry.npmjs.org/raw-body/-/raw-body-2.4.2.tgz",
"integrity": "sha512-RPMAFUJP19WIet/99ngh6Iv8fzAbqum4Li7AD6DtGaW2RpMB/11xDoalPiJMTbu6I3hkbMVkATvZrqb9EEqeeQ==",
"version": "2.4.3",
"resolved": "https://registry.npmjs.org/raw-body/-/raw-body-2.4.3.tgz",
"integrity": "sha512-UlTNLIcu0uzb4D2f4WltY6cVjLi+/jEN4lgEUj3E04tpMDpUlkBo/eSn6zou9hum2VMNpCCUone0O0WeJim07g==",
"dev": true,
"requires": {
"bytes": "3.1.1",
"bytes": "3.1.2",
"http-errors": "1.8.1",
"iconv-lite": "0.4.24",
"unpipe": "1.0.0"

2
package.json
View File

@@ -12,7 +12,7 @@
},
"devDependencies": {
"jasmine-core": "^3.4.0",
"karma": "^6.3.14",
"karma": "^6.3.16",
"karma-firefox-launcher": "^2.0.0",
"karma-jasmine": "^4.0.0"
}

25
setup.cfg
View File

@@ -1,5 +1,5 @@
[metadata]
license_file = LICENSE
license_files = LICENSE
[egg_info]
tag_build = .dev
@@ -9,23 +9,6 @@ tag_date = true
release = egg_info -Db ''
upload = upload --sign --identity=36580288
[build_sphinx]
warning-is-error = 1
[extract_messages]
mapping_file = babel.cfg
output_file = sphinx/locale/sphinx.pot
keywords = _ __ l_ lazy_gettext
[update_catalog]
input_file = sphinx/locale/sphinx.pot
domain = sphinx
output_dir = sphinx/locale/
[compile_catalog]
domain = sphinx
directory = sphinx/locale/
[flake8]
max-line-length = 95
ignore = E116,E241,E251,E741,W504,I101
@@ -35,12 +18,6 @@ import-order-style = smarkets
per-file-ignores =
tests/*: E501
[flake8:local-plugins]
extension =
X101 = utils.checks:sphinx_has_header
paths =
.
[isort]
line_length = 95

126
setup.py
View File

@@ -1,12 +1,10 @@
import os
import sys
from io import StringIO
from setuptools import find_packages, setup
import sphinx
with open('README.rst') as f:
with open('README.rst', encoding='utf-8') as f:
long_desc = f.read()
if sys.version_info < (3, 6):
@@ -22,7 +20,7 @@ install_requires = [
'sphinxcontrib-qthelp',
'Jinja2>=2.3',
'Pygments>=2.0',
'docutils>=0.14,<0.18',
'docutils>=0.14,<0.19',
'snowballstemmer>=1.1',
'babel>=1.3',
'alabaster>=0.7,<0.8',
@@ -43,134 +41,19 @@ extras_require = {
'lint': [
'flake8>=3.5.0',
'isort',
'mypy>=0.931',
'mypy>=0.950',
'docutils-stubs',
"types-typed-ast",
"types-requests",
],
'test': [
'pytest',
'pytest-cov',
'pytest>=4.6',
'html5lib',
"typed_ast; python_version < '3.8'",
'cython',
],
}
# Provide a "compile_catalog" command that also creates the translated
# JavaScript files if Babel is available.
cmdclass = {}
class Tee:
def __init__(self, stream):
self.stream = stream
self.buffer = StringIO()
def write(self, s):
self.stream.write(s)
self.buffer.write(s)
def flush(self):
self.stream.flush()
try:
from json import dump
from babel.messages.frontend import compile_catalog
from babel.messages.pofile import read_po
except ImportError:
pass
else:
class compile_catalog_plusjs(compile_catalog):
"""
An extended command that writes all message strings that occur in
JavaScript files to a JavaScript file along with the .mo file.
Unfortunately, babel's setup command isn't built very extensible, so
most of the run() code is duplicated here.
"""
def run(self):
try:
sys.stderr = Tee(sys.stderr)
compile_catalog.run(self)
finally:
if sys.stderr.buffer.getvalue():
print("Compiling failed.")
sys.exit(1)
if isinstance(self.domain, list):
for domain in self.domain:
self._run_domain_js(domain)
else:
self._run_domain_js(self.domain)
def _run_domain_js(self, domain):
po_files = []
js_files = []
if not self.input_file:
if self.locale:
po_files.append((self.locale,
os.path.join(self.directory, self.locale,
'LC_MESSAGES',
domain + '.po')))
js_files.append(os.path.join(self.directory, self.locale,
'LC_MESSAGES',
domain + '.js'))
else:
for locale in os.listdir(self.directory):
po_file = os.path.join(self.directory, locale,
'LC_MESSAGES',
domain + '.po')
if os.path.exists(po_file):
po_files.append((locale, po_file))
js_files.append(os.path.join(self.directory, locale,
'LC_MESSAGES',
domain + '.js'))
else:
po_files.append((self.locale, self.input_file))
if self.output_file:
js_files.append(self.output_file)
else:
js_files.append(os.path.join(self.directory, self.locale,
'LC_MESSAGES',
domain + '.js'))
for js_file, (locale, po_file) in zip(js_files, po_files):
with open(po_file, encoding='utf8') as infile:
catalog = read_po(infile, locale)
if catalog.fuzzy and not self.use_fuzzy:
continue
self.log.info('writing JavaScript strings in catalog %r to %r',
po_file, js_file)
jscatalog = {}
for message in catalog:
if any(x[0].endswith(('.js', '.js_t', '.html'))
for x in message.locations):
msgid = message.id
if isinstance(msgid, (list, tuple)):
msgid = msgid[0]
jscatalog[msgid] = message.string
with open(js_file, 'wt', encoding='utf8') as outfile:
outfile.write('Documentation.addTranslations(')
dump({
'messages': jscatalog,
'plural_expr': catalog.plural_expr,
'locale': str(catalog.locale)
}, outfile, sort_keys=True, indent=4)
outfile.write(');')
cmdclass['compile_catalog'] = compile_catalog_plusjs
setup(
name='Sphinx',
version=sphinx.__version__,
@@ -246,5 +129,4 @@ setup(
python_requires=">=3.6",
install_requires=install_requires,
extras_require=extras_require,
cmdclass=cmdclass,
)

12
sphinx/__init__.py
View File

@@ -1,12 +1,4 @@
"""
Sphinx
~~~~~~
The Sphinx documentation toolchain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The Sphinx documentation toolchain."""
# Keep this file executable as-is in Python 3!
# (Otherwise getting the version out of it from setup.py is impossible.)
@@ -26,6 +18,8 @@ if 'PYTHONWARNINGS' not in os.environ:
# docutils.io using mode='rU' for open
warnings.filterwarnings('ignore', "'U' mode is deprecated",
DeprecationWarning, module='docutils.io')
warnings.filterwarnings('ignore', 'The frontend.Option class .*',
DeprecationWarning, module='docutils.frontend')
__version__ = '5.0.0+'
__released__ = '5.0.0' # used when Sphinx builds its own docs

10
sphinx/__main__.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.__main__
~~~~~~~~~~~~~~~
The Sphinx documentation toolchain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The Sphinx documentation toolchain."""
import sys

14
sphinx/addnodes.py
View File

@@ -1,15 +1,8 @@
"""
sphinx.addnodes
~~~~~~~~~~~~~~~
Additional docutils nodes.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Additional docutils nodes."""
from typing import TYPE_CHECKING, Any, Dict, List, Sequence
import docutils
from docutils import nodes
from docutils.nodes import Element
@@ -36,7 +29,6 @@ class document(nodes.document):
def set_id(self, node: Element, msgnode: Element = None,
suggested_prefix: str = '') -> str:
from sphinx.util import docutils
if docutils.__version_info__ >= (0, 16):
ret = super().set_id(node, msgnode, suggested_prefix) # type: ignore
else:
@@ -535,8 +527,6 @@ class manpage(nodes.Inline, nodes.FixedTextElement):
def setup(app: "Sphinx") -> Dict[str, Any]:
from sphinx.util import docutils # lazy import
app.add_node(toctree)
app.add_node(desc)

11
sphinx/application.py
View File

@@ -1,13 +1,6 @@
"""
sphinx.application
~~~~~~~~~~~~~~~~~~
"""Sphinx application class and extensibility interface.
Sphinx application class and extensibility interface.
Gracefully adapted from the TextPress system by Armin.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
Gracefully adapted from the TextPress system by Armin.
"""
import os

10
sphinx/builders/__init__.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders
~~~~~~~~~~~~~~~
Builder superclass for all builders.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Builder superclass for all builders."""
import pickle
import time

12
sphinx/builders/_epub_base.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders._epub_base
~~~~~~~~~~~~~~~~~~~~~~~~~~
Base class of epub2/epub3 builders.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Base class of epub2/epub3 builders."""
import html
import os
@@ -491,7 +483,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
metadata['copyright'] = html.escape(self.config.epub_copyright)
metadata['scheme'] = html.escape(self.config.epub_scheme)
metadata['id'] = html.escape(self.config.epub_identifier)
metadata['date'] = html.escape(format_date("%Y-%m-%d"))
metadata['date'] = html.escape(format_date("%Y-%m-%d", language='en'))
metadata['manifest_items'] = []
metadata['spines'] = []
metadata['guides'] = []

10
sphinx/builders/changes.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.changes
~~~~~~~~~~~~~~~~~~~~~~~
Changelog builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Changelog builder."""
import html
from os import path

10
sphinx/builders/dirhtml.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.dirhtml
~~~~~~~~~~~~~~~~~~~~~~~
Directory HTML builders.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Directory HTML builders."""
from os import path
from typing import Any, Dict

10
sphinx/builders/dummy.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.dummy
~~~~~~~~~~~~~~~~~~~~~
Do syntax checks, but no writing.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Do syntax checks, but no writing."""
from typing import Any, Dict, Set

12
sphinx/builders/epub3.py
View File

@@ -1,12 +1,6 @@
"""
sphinx.builders.epub3
~~~~~~~~~~~~~~~~~~~~~
"""Build epub3 files.
Build epub3 files.
Originally derived from epub.py.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
Originally derived from epub.py.
"""
import html
@@ -94,7 +88,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
metadata['contributor'] = html.escape(self.config.epub_contributor)
metadata['page_progression_direction'] = PAGE_PROGRESSION_DIRECTIONS.get(writing_mode)
metadata['ibook_scroll_axis'] = IBOOK_SCROLL_AXIS.get(writing_mode)
metadata['date'] = html.escape(format_date("%Y-%m-%dT%H:%M:%SZ"))
metadata['date'] = html.escape(format_date("%Y-%m-%dT%H:%M:%SZ", language='en'))
metadata['version'] = html.escape(self.config.version)
metadata['epub_version'] = self.config.epub_version
return metadata

10
sphinx/builders/gettext.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.gettext
~~~~~~~~~~~~~~~~~~~~~~~
The MessageCatalogBuilder class.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The MessageCatalogBuilder class."""
from codecs import open
from collections import OrderedDict, defaultdict

69
sphinx/builders/html/__init__.py
View File

@@ -1,21 +1,14 @@
"""
sphinx.builders.html
~~~~~~~~~~~~~~~~~~~~
Several HTML builders.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Several HTML builders."""
import html
import os
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, Type
from typing import IO, Any, Dict, Iterable, Iterator, List, Optional, Set, Tuple, Type
from urllib.parse import quote
from docutils import nodes
@@ -30,6 +23,7 @@ from sphinx import version_info as sphinx_version
from sphinx.application import Sphinx
from sphinx.builders import Builder
from sphinx.config import ENUM, Config
from sphinx.deprecation import RemovedInSphinx70Warning, deprecated_alias
from sphinx.domains import Domain, Index, IndexEntry
from sphinx.environment.adapters.asset import ImageAdapter
from sphinx.environment.adapters.indexentries import IndexEntries
@@ -40,7 +34,7 @@ from sphinx.locale import _, __
from sphinx.search import js_index
from sphinx.theming import HTMLThemeFactory
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.docutils import new_document
from sphinx.util.fileutil import copy_asset
from sphinx.util.i18n import format_date
from sphinx.util.inventory import InventoryFile
@@ -48,13 +42,7 @@ from sphinx.util.matching import DOTFILES, Matcher, patmatch
from sphinx.util.osutil import copyfile, ensuredir, os_path, relative_uri
from sphinx.util.tags import Tags
from sphinx.writers.html import HTMLTranslator, HTMLWriter
# HTML5 Writer is available or not
if is_html5_writer_available():
from sphinx.writers.html5 import HTML5Translator
html5_ready = True
else:
html5_ready = False
from sphinx.writers.html5 import HTML5Translator
#: the filename for the inventory of objects
INVENTORY_FILENAME = 'objects.inv'
@@ -76,6 +64,17 @@ def get_stable_hash(obj: Any) -> str:
return md5(str(obj).encode()).hexdigest()
def convert_locale_to_language_tag(locale: Optional[str]) -> Optional[str]:
"""Convert a locale string to a language tag (ex. en_US -> en-US).
refs: BCP 47 (:rfc:`5646`)
"""
if locale:
return locale.replace('_', '-')
else:
return None
class Stylesheet(str):
"""A metadata of stylesheet.
@@ -340,7 +339,7 @@ class StandaloneHTMLBuilder(Builder):
@property
def default_translator_class(self) -> Type[nodes.NodeVisitor]: # type: ignore
if not html5_ready or self.config.html4_writer:
if self.config.html4_writer:
return HTMLTranslator
else:
return HTML5Translator
@@ -367,7 +366,7 @@ class StandaloneHTMLBuilder(Builder):
def get_outdated_docs(self) -> Iterator[str]:
try:
with open(path.join(self.outdir, '.buildinfo')) as fp:
with open(path.join(self.outdir, '.buildinfo'), encoding="utf-8") as fp:
buildinfo = BuildInfo.load(fp)
if self.build_info != buildinfo:
@@ -440,10 +439,14 @@ class StandaloneHTMLBuilder(Builder):
self.load_indexer(docnames)
self.docwriter = HTMLWriter(self)
self.docsettings: Any = OptionParser(
defaults=self.env.settings,
components=(self.docwriter,),
read_config_files=True).get_default_values()
with warnings.catch_warnings():
warnings.filterwarnings('ignore', category=DeprecationWarning)
# DeprecationWarning: The frontend.OptionParser class will be replaced
# by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
self.docsettings: Any = OptionParser(
defaults=self.env.settings,
components=(self.docwriter,),
read_config_files=True).get_default_values()
self.docsettings.compact_lists = bool(self.config.html_compact_lists)
# determine the additional indices to include
@@ -518,7 +521,7 @@ class StandaloneHTMLBuilder(Builder):
'file_suffix': self.out_suffix,
'link_suffix': self.link_suffix,
'script_files': self.script_files,
'language': self.config.language,
'language': convert_locale_to_language_tag(self.config.language),
'css_files': self.css_files,
'sphinx_version': __display_version__,
'sphinx_version_tuple': sphinx_version,
@@ -528,7 +531,7 @@ class StandaloneHTMLBuilder(Builder):
'parents': [],
'logo': logo,
'favicon': favicon,
'html5_doctype': html5_ready and not self.config.html4_writer,
'html5_doctype': not self.config.html4_writer,
}
if self.theme:
self.globalcontext.update(
@@ -760,11 +763,13 @@ class StandaloneHTMLBuilder(Builder):
def create_pygments_style_file(self) -> None:
"""create a style file for pygments."""
with open(path.join(self.outdir, '_static', 'pygments.css'), 'w') as f:
with open(path.join(self.outdir, '_static', 'pygments.css'), 'w',
encoding="utf-8") as f:
f.write(self.highlighter.get_stylesheet())
if self.dark_highlighter:
with open(path.join(self.outdir, '_static', 'pygments_dark.css'), 'w') as f:
with open(path.join(self.outdir, '_static', 'pygments_dark.css'), 'w',
encoding="utf-8") as f:
f.write(self.dark_highlighter.get_stylesheet())
def copy_translation_js(self) -> None:
@@ -850,7 +855,7 @@ class StandaloneHTMLBuilder(Builder):
def write_buildinfo(self) -> None:
try:
with open(path.join(self.outdir, '.buildinfo'), 'w') as fp:
with open(path.join(self.outdir, '.buildinfo'), 'w', encoding="utf-8") as fp:
self.build_info.dump(fp)
except OSError as exc:
logger.warning(__('Failed to write build info file: %r'), exc)
@@ -1305,6 +1310,12 @@ import sphinxcontrib.serializinghtml # NOQA
import sphinx.builders.dirhtml # NOQA
import sphinx.builders.singlehtml # NOQA
deprecated_alias('sphinx.builders.html',
{
'html5_ready': True,
},
RemovedInSphinx70Warning)
def setup(app: Sphinx) -> Dict[str, Any]:
# builders

10
sphinx/builders/html/transforms.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.html.transforms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Transforms for HTML builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Transforms for HTML builder."""
import re
from typing import Any, Dict, List

29
sphinx/builders/latex/__init__.py
View File

@@ -1,14 +1,7 @@
"""
sphinx.builders.latex
~~~~~~~~~~~~~~~~~~~~~
LaTeX builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""LaTeX builder."""
import os
import warnings
from os import path
from typing import Any, Dict, Iterable, List, Tuple, Union
@@ -249,7 +242,7 @@ class LaTeXBuilder(Builder):
def write_stylesheet(self) -> None:
highlighter = highlighting.PygmentsBridge('latex', self.config.pygments_style)
stylesheet = path.join(self.outdir, 'sphinxhighlight.sty')
with open(stylesheet, 'w') as f:
with open(stylesheet, 'w', encoding="utf-8") as f:
f.write('\\NeedsTeXFormat{LaTeX2e}[1995/12/01]\n')
f.write('\\ProvidesPackage{sphinxhighlight}'
'[2016/05/29 stylesheet for highlighting with pygments]\n')
@@ -258,10 +251,14 @@ class LaTeXBuilder(Builder):
def write(self, *ignored: Any) -> None:
docwriter = LaTeXWriter(self)
docsettings: Any = OptionParser(
defaults=self.env.settings,
components=(docwriter,),
read_config_files=True).get_default_values()
with warnings.catch_warnings():
warnings.filterwarnings('ignore', category=DeprecationWarning)
# DeprecationWarning: The frontend.OptionParser class will be replaced
# by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
docsettings: Any = OptionParser(
defaults=self.env.settings,
components=(docwriter,),
read_config_files=True).get_default_values()
self.init_document_data()
self.write_stylesheet()
@@ -355,9 +352,9 @@ class LaTeXBuilder(Builder):
newnodes: List[Node] = [nodes.emphasis(sectname, sectname)]
for subdir, title in self.titles:
if docname.startswith(subdir):
newnodes.append(nodes.Text(_(' (in '), _(' (in ')))
newnodes.append(nodes.Text(_(' (in ')))
newnodes.append(nodes.emphasis(title, title))
newnodes.append(nodes.Text(')', ')'))
newnodes.append(nodes.Text(')'))
break
else:
pass

10
sphinx/builders/latex/constants.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.latex.constants
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
consntants for LaTeX builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""consntants for LaTeX builder."""
from typing import Any, Dict

10
sphinx/builders/latex/nodes.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.latex.nodes
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Additional nodes for LaTeX writer.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Additional nodes for LaTeX writer."""
from docutils import nodes

12
sphinx/builders/latex/theming.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.latex.theming
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Theming support for LaTeX builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Theming support for LaTeX builder."""
import configparser
from os import path
@@ -81,7 +73,7 @@ class UserTheme(Theme):
def __init__(self, name: str, filename: str) -> None:
super().__init__(name)
self.config = configparser.RawConfigParser()
self.config.read(path.join(filename))
self.config.read(path.join(filename), encoding='utf-8')
for key in self.REQUIRED_CONFIG_KEYS:
try:

10
sphinx/builders/latex/transforms.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.latex.transforms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Transforms for LaTeX builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Transforms for LaTeX builder."""
from typing import Any, Dict, List, Set, Tuple, cast

10
sphinx/builders/latex/util.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.latex.util
~~~~~~~~~~~~~~~~~~~~~~~~~~
Utilities for LaTeX builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Utilities for LaTeX builder."""
from typing import Optional

16
sphinx/builders/linkcheck.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.linkcheck
~~~~~~~~~~~~~~~~~~~~~~~~~
The CheckExternalLinksBuilder class.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The CheckExternalLinksBuilder class."""
import json
import re
@@ -192,8 +184,10 @@ class CheckExternalLinksBuilder(DummyBuilder):
checker = HyperlinkAvailabilityChecker(self.env, self.config)
logger.info('')
with open(path.join(self.outdir, 'output.txt'), 'w') as self.txt_outfile,\
open(path.join(self.outdir, 'output.json'), 'w') as self.json_outfile:
output_text = path.join(self.outdir, 'output.txt')
output_json = path.join(self.outdir, 'output.json')
with open(output_text, 'w', encoding="utf-8") as self.txt_outfile,\
open(output_json, 'w', encoding="utf-8") as self.json_outfile:
for result in checker.check(self.hyperlinks):
self.process_result(result)

28
sphinx/builders/manpage.py
View File

@@ -1,13 +1,6 @@
"""
sphinx.builders.manpage
~~~~~~~~~~~~~~~~~~~~~~~
Manual pages builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Manual pages builder."""
import warnings
from os import path
from typing import Any, Dict, List, Set, Tuple, Union
@@ -18,7 +11,6 @@ from sphinx import addnodes
from sphinx.application import Sphinx
from sphinx.builders import Builder
from sphinx.config import Config
from sphinx.errors import NoUri
from sphinx.locale import __
from sphinx.util import logging, progress_message
from sphinx.util.console import darkgreen # type: ignore
@@ -49,17 +41,19 @@ class ManualPageBuilder(Builder):
return 'all manpages' # for now
def get_target_uri(self, docname: str, typ: str = None) -> str:
if typ == 'token':
return ''
raise NoUri(docname, typ)
return ''
@progress_message(__('writing'))
def write(self, *ignored: Any) -> None:
docwriter = ManualPageWriter(self)
docsettings: Any = OptionParser(
defaults=self.env.settings,
components=(docwriter,),
read_config_files=True).get_default_values()
with warnings.catch_warnings():
warnings.filterwarnings('ignore', category=DeprecationWarning)
# DeprecationWarning: The frontend.OptionParser class will be replaced
# by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
docsettings: Any = OptionParser(
defaults=self.env.settings,
components=(docwriter,),
read_config_files=True).get_default_values()
for info in self.config.man_pages:
docname, name, description, authors, section = info

10
sphinx/builders/singlehtml.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.singlehtml
~~~~~~~~~~~~~~~~~~~~~~~~~~
Single HTML builders.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Single HTML builders."""
from os import path
from typing import Any, Dict, List, Tuple, Union

27
sphinx/builders/texinfo.py
View File

@@ -1,14 +1,7 @@
"""
sphinx.builders.texinfo
~~~~~~~~~~~~~~~~~~~~~~~
Texinfo builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Texinfo builder."""
import os
import warnings
from os import path
from typing import Any, Dict, Iterable, List, Tuple, Union
@@ -109,10 +102,14 @@ class TexinfoBuilder(Builder):
with progress_message(__("writing")):
self.post_process_images(doctree)
docwriter = TexinfoWriter(self)
settings: Any = OptionParser(
defaults=self.env.settings,
components=(docwriter,),
read_config_files=True).get_default_values()
with warnings.catch_warnings():
warnings.filterwarnings('ignore', category=DeprecationWarning)
# DeprecationWarning: The frontend.OptionParser class will be replaced
# by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
settings: Any = OptionParser(
defaults=self.env.settings,
components=(docwriter,),
read_config_files=True).get_default_values()
settings.author = author
settings.title = title
settings.texinfo_filename = targetname[:-5] + '.info'
@@ -158,9 +155,9 @@ class TexinfoBuilder(Builder):
newnodes: List[Node] = [nodes.emphasis(sectname, sectname)]
for subdir, title in self.titles:
if docname.startswith(subdir):
newnodes.append(nodes.Text(_(' (in '), _(' (in ')))
newnodes.append(nodes.Text(_(' (in ')))
newnodes.append(nodes.emphasis(title, title))
newnodes.append(nodes.Text(')', ')'))
newnodes.append(nodes.Text(')'))
break
else:
pass

10
sphinx/builders/text.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.text
~~~~~~~~~~~~~~~~~~~~
Plain-text Sphinx builder.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Plain-text Sphinx builder."""
from os import path
from typing import Any, Dict, Iterator, Set, Tuple

10
sphinx/builders/xml.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.builders.xml
~~~~~~~~~~~~~~~~~~~
Docutils-native XML and pseudo-XML builders.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Docutils-native XML and pseudo-XML builders."""
from os import path
from typing import Any, Dict, Iterator, Set, Type, Union

10
sphinx/cmd/__init__.py
View File

@@ -1,9 +1 @@
"""
sphinx.cmd
~~~~~~~~~~
Modules for command line executables.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Modules for command line executables."""

12
sphinx/cmd/build.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.cmd.build
~~~~~~~~~~~~~~~~
Build documentation from a provided source.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Build documentation from a provided source."""
import argparse
import bdb
@@ -244,7 +236,7 @@ def build_main(argv: List[str] = sys.argv[1:]) -> int:
try:
warnfile = abspath(args.warnfile)
ensuredir(path.dirname(warnfile))
warnfp = open(args.warnfile, 'w')
warnfp = open(args.warnfile, 'w', encoding="utf-8")
except Exception as exc:
parser.error(__('cannot open warning file %r: %s') % (
args.warnfile, exc))

17
sphinx/cmd/make_mode.py
View File

@@ -1,17 +1,10 @@
"""
sphinx.cmd.make_mode
~~~~~~~~~~~~~~~~~~~~
"""sphinx-build -M command-line handling.
sphinx-build -M command-line handling.
This replaces the old, platform-dependent and once-generated content
of Makefile / make.bat.
This replaces the old, platform-dependent and once-generated content
of Makefile / make.bat.
This is in its own module so that importing it is fast. It should not
import the main Sphinx modules (like sphinx.applications, sphinx.builders).
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
This is in its own module so that importing it is fast. It should not
import the main Sphinx modules (like sphinx.applications, sphinx.builders).
"""
import os

12
sphinx/cmd/quickstart.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.cmd.quickstart
~~~~~~~~~~~~~~~~~~~~~
Quickly setup documentation source to work with Sphinx.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Quickly setup documentation source to work with Sphinx."""
import argparse
import locale
@@ -375,7 +367,7 @@ def generate(d: Dict, overwrite: bool = True, silent: bool = False, templatedir:
conf_path = os.path.join(templatedir, 'conf.py_t') if templatedir else None
if not conf_path or not path.isfile(conf_path):
conf_path = os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')
with open(conf_path) as f:
with open(conf_path, encoding="utf-8") as f:
conf_text = f.read()
write_file(path.join(srcdir, 'conf.py'), template.render_string(conf_text, d))

12
sphinx/config.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.config
~~~~~~~~~~~~~
Build configuration file handling.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Build configuration file handling."""
import re
import traceback
@@ -413,7 +405,7 @@ def correct_copyright_year(app: "Sphinx", config: Config) -> None:
if getenv('SOURCE_DATE_EPOCH') is not None:
for k in ('copyright', 'epub_copyright'):
if k in config:
replace = r'\g<1>%s' % format_date('%Y')
replace = r'\g<1>%s' % format_date('%Y', language='en')
config[k] = copyright_year_re.sub(replace, config[k])

18
sphinx/deprecation.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.deprecation
~~~~~~~~~~~~~~~~~~
Sphinx deprecation classes and utilities.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Sphinx deprecation classes and utilities."""
import sys
import warnings
@@ -14,11 +6,7 @@ from importlib import import_module
from typing import Any, Dict, Type
class RemovedInSphinx50Warning(DeprecationWarning):
pass
class RemovedInSphinx60Warning(PendingDeprecationWarning):
class RemovedInSphinx60Warning(DeprecationWarning):
pass
@@ -26,7 +14,7 @@ class RemovedInSphinx70Warning(PendingDeprecationWarning):
pass
RemovedInNextVersionWarning = RemovedInSphinx50Warning
RemovedInNextVersionWarning = RemovedInSphinx60Warning
def deprecated_alias(modname: str, objects: Dict[str, object],

10
sphinx/directives/__init__.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.directives
~~~~~~~~~~~~~~~~~
Handlers for additional ReST directives.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Handlers for additional ReST directives."""
import re
from typing import TYPE_CHECKING, Any, Dict, Generic, List, Tuple, TypeVar, cast

12
sphinx/directives/code.py
View File

@@ -1,11 +1,3 @@
"""
sphinx.directives.code
~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import sys
import textwrap
from difflib import unified_diff
@@ -232,9 +224,9 @@ class LiteralIncludeReader:
self.start_filter,
self.end_filter,
self.lines_filter,
self.dedent_filter,
self.prepend_filter,
self.append_filter,
self.dedent_filter]
self.append_filter]
lines = self.read_file(self.filename, location=location)
for func in filters:
lines = func(lines, location=location)

10
sphinx/directives/other.py
View File

@@ -1,11 +1,3 @@
"""
sphinx.directives.other
~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import re
from typing import TYPE_CHECKING, Any, Dict, List, cast
@@ -180,7 +172,7 @@ class Author(SphinxDirective):
text = _('Code author: ')
else:
text = _('Author: ')
emph += nodes.Text(text, text)
emph += nodes.Text(text)
inodes, messages = self.state.inline_text(self.arguments[0], self.lineno)
emph.extend(inodes)

8
sphinx/directives/patches.py
View File

@@ -1,11 +1,3 @@
"""
sphinx.directives.patches
~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import os
import warnings
from os import path

11
sphinx/domains/__init__.py
View File

@@ -1,12 +1,7 @@
"""
sphinx.domains
~~~~~~~~~~~~~~
"""Support for domains.
Support for domains, which are groupings of description directives
and roles describing e.g. constructs of one programming language.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
Domains are groupings of description directives
and roles describing e.g. constructs of one programming language.
"""
import copy

77
sphinx/domains/c.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.c
~~~~~~~~~~~~~~~~
The C language domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The C language domain."""
import re
from typing import (Any, Callable, Dict, Generator, Iterator, List, Optional, Tuple, TypeVar,
@@ -29,8 +21,8 @@ from sphinx.roles import SphinxRole, XRefRole
from sphinx.transforms import SphinxTransform
from sphinx.transforms.post_transforms import ReferencesResolver
from sphinx.util import logging
from sphinx.util.cfamily import (ASTAttribute, ASTBaseBase, ASTBaseParenExprList, BaseParser,
DefinitionError, NoOldIdError, StringifyTransform,
from sphinx.util.cfamily import (ASTAttributeList, ASTBaseBase, ASTBaseParenExprList,
BaseParser, DefinitionError, NoOldIdError, StringifyTransform,
UnsupportedMultiCharacterCharLiteral, anon_identifier_re,
binary_literal_re, char_literal_re, float_literal_re,
float_literal_suffix_re, hex_literal_re, identifier_re,
@@ -695,7 +687,7 @@ class ASTFunctionParameter(ASTBase):
class ASTParameters(ASTBase):
def __init__(self, args: List[ASTFunctionParameter], attrs: List[ASTAttribute]) -> None:
def __init__(self, args: List[ASTFunctionParameter], attrs: ASTAttributeList) -> None:
self.args = args
self.attrs = attrs
@@ -713,9 +705,9 @@ class ASTParameters(ASTBase):
first = False
res.append(str(a))
res.append(')')
for attr in self.attrs:
if len(self.attrs) != 0:
res.append(' ')
res.append(transform(attr))
res.append(transform(self.attrs))
return ''.join(res)
def describe_signature(self, signode: TextElement, mode: str,
@@ -740,14 +732,14 @@ class ASTParameters(ASTBase):
arg.describe_signature(signode, 'markType', env, symbol=symbol)
signode += addnodes.desc_sig_punctuation(')', ')')
for attr in self.attrs:
if len(self.attrs) != 0:
signode += addnodes.desc_sig_space()
attr.describe_signature(signode)
self.attrs.describe_signature(signode)
class ASTDeclSpecsSimple(ASTBaseBase):
def __init__(self, storage: str, threadLocal: str, inline: bool,
restrict: bool, volatile: bool, const: bool, attrs: List[Any]) -> None:
restrict: bool, volatile: bool, const: bool, attrs: ASTAttributeList) -> None:
self.storage = storage
self.threadLocal = threadLocal
self.inline = inline
@@ -769,7 +761,8 @@ class ASTDeclSpecsSimple(ASTBaseBase):
def _stringify(self, transform: StringifyTransform) -> str:
res: List[str] = []
res.extend(transform(attr) for attr in self.attrs)
if len(self.attrs) != 0:
res.append(transform(self.attrs))
if self.storage:
res.append(self.storage)
if self.threadLocal:
@@ -786,14 +779,15 @@ class ASTDeclSpecsSimple(ASTBaseBase):
def describe_signature(self, modifiers: List[Node]) -> None:
def _add(modifiers: List[Node], text: str) -> None:
if len(modifiers) > 0:
if len(modifiers) != 0:
modifiers.append(addnodes.desc_sig_space())
modifiers.append(addnodes.desc_sig_keyword(text, text))
for attr in self.attrs:
if len(modifiers) > 0:
modifiers.append(addnodes.desc_sig_space())
modifiers.append(attr.describe_signature(modifiers))
if len(modifiers) != 0 and len(self.attrs) != 0:
modifiers.append(addnodes.desc_sig_space())
tempNode = nodes.TextElement()
self.attrs.describe_signature(tempNode)
modifiers.extend(tempNode.children)
if self.storage:
_add(modifiers, self.storage)
if self.threadLocal:
@@ -1010,7 +1004,7 @@ class ASTDeclaratorNameBitField(ASTDeclarator):
class ASTDeclaratorPtr(ASTDeclarator):
def __init__(self, next: ASTDeclarator, restrict: bool, volatile: bool, const: bool,
attrs: Any) -> None:
attrs: ASTAttributeList) -> None:
assert next
self.next = next
self.restrict = restrict
@@ -1033,9 +1027,8 @@ class ASTDeclaratorPtr(ASTDeclarator):
def _stringify(self, transform: StringifyTransform) -> str:
res = ['*']
for a in self.attrs:
res.append(transform(a))
if len(self.attrs) > 0 and (self.restrict or self.volatile or self.const):
res.append(transform(self.attrs))
if len(self.attrs) != 0 and (self.restrict or self.volatile or self.const):
res.append(' ')
if self.restrict:
res.append('restrict')
@@ -1057,9 +1050,8 @@ class ASTDeclaratorPtr(ASTDeclarator):
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
signode += addnodes.desc_sig_punctuation('*', '*')
for a in self.attrs:
a.describe_signature(signode)
if len(self.attrs) > 0 and (self.restrict or self.volatile or self.const):
self.attrs.describe_signature(signode)
if len(self.attrs) != 0 and (self.restrict or self.volatile or self.const):
signode += addnodes.desc_sig_space()
def _add_anno(signode: TextElement, text: str) -> None:
@@ -1382,9 +1374,11 @@ class ASTEnum(ASTBase):
class ASTEnumerator(ASTBase):
def __init__(self, name: ASTNestedName, init: ASTInitializer) -> None:
def __init__(self, name: ASTNestedName, init: Optional[ASTInitializer],
attrs: ASTAttributeList) -> None:
self.name = name
self.init = init
self.attrs = attrs
def get_id(self, version: int, objectType: str, symbol: "Symbol") -> str:
return symbol.get_full_nested_name().get_id(version)
@@ -1392,6 +1386,9 @@ class ASTEnumerator(ASTBase):
def _stringify(self, transform: StringifyTransform) -> str:
res = []
res.append(transform(self.name))
if len(self.attrs) != 0:
res.append(' ')
res.append(transform(self.attrs))
if self.init:
res.append(transform(self.init))
return ''.join(res)
@@ -1400,6 +1397,9 @@ class ASTEnumerator(ASTBase):
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
self.name.describe_signature(signode, mode, env, symbol)
if len(self.attrs) != 0:
signode += addnodes.desc_sig_space()
self.attrs.describe_signature(signode)
if self.init:
self.init.describe_signature(signode, 'markType', env, symbol)
@@ -2649,13 +2649,7 @@ class DefinitionParser(BaseParser):
'Expecting "," or ")" in parameters, '
'got "%s".' % self.current_char)
attrs = []
while True:
attr = self._parse_attribute()
if attr is None:
break
attrs.append(attr)
attrs = self._parse_attribute_list()
return ASTParameters(args, attrs)
def _parse_decl_specs_simple(self, outer: str, typed: bool) -> ASTDeclSpecsSimple:
@@ -2714,7 +2708,7 @@ class DefinitionParser(BaseParser):
continue
break
return ASTDeclSpecsSimple(storage, threadLocal, inline,
restrict, volatile, const, attrs)
restrict, volatile, const, ASTAttributeList(attrs))
def _parse_decl_specs(self, outer: str, typed: bool = True) -> ASTDeclSpecs:
if outer:
@@ -2846,7 +2840,7 @@ class DefinitionParser(BaseParser):
next = self._parse_declarator(named, paramMode, typed)
return ASTDeclaratorPtr(next=next,
restrict=restrict, volatile=volatile, const=const,
attrs=attrs)
attrs=ASTAttributeList(attrs))
if typed and self.current_char == '(': # note: peeking, not skipping
# maybe this is the beginning of params, try that first,
# otherwise assume it's noptr->declarator > ( ptr-declarator )
@@ -3041,6 +3035,7 @@ class DefinitionParser(BaseParser):
def _parse_enumerator(self) -> ASTEnumerator:
name = self._parse_nested_name()
attrs = self._parse_attribute_list()
self.skip_ws()
init = None
if self.skip_string('='):
@@ -3051,7 +3046,7 @@ class DefinitionParser(BaseParser):
initVal = self._parse_expression_fallback([], parser)
init = ASTInitializer(initVal)
return ASTEnumerator(name, init)
return ASTEnumerator(name, init, attrs)
def parse_pre_v3_type_definition(self) -> ASTDeclaration:
self.skip_ws()

10
sphinx/domains/changeset.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.changeset
~~~~~~~~~~~~~~~~~~~~~~~~
The changeset domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The changeset domain."""
from typing import TYPE_CHECKING, Any, Dict, List, NamedTuple, cast

10
sphinx/domains/citation.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.citation
~~~~~~~~~~~~~~~~~~~~~~~
The citation domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The citation domain."""
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set, Tuple, cast

311
sphinx/domains/cpp.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.cpp
~~~~~~~~~~~~~~~~~~
The C++ language domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The C++ language domain."""
import re
from typing import (Any, Callable, Dict, Generator, Iterator, List, Optional, Tuple, TypeVar,
@@ -29,8 +21,8 @@ from sphinx.roles import SphinxRole, XRefRole
from sphinx.transforms import SphinxTransform
from sphinx.transforms.post_transforms import ReferencesResolver
from sphinx.util import logging
from sphinx.util.cfamily import (ASTAttribute, ASTBaseBase, ASTBaseParenExprList, BaseParser,
DefinitionError, NoOldIdError, StringifyTransform,
from sphinx.util.cfamily import (ASTAttributeList, ASTBaseBase, ASTBaseParenExprList,
BaseParser, DefinitionError, NoOldIdError, StringifyTransform,
UnsupportedMultiCharacterCharLiteral, anon_identifier_re,
binary_literal_re, char_literal_re, float_literal_re,
float_literal_suffix_re, hex_literal_re, identifier_re,
@@ -267,7 +259,8 @@ T = TypeVar('T')
class_object:
goal: a class declaration, but with specification of a base class
grammar:
nested-name "final"[opt] (":" base-specifier-list)[opt]
attribute-specifier-seq[opt]
nested-name "final"[opt] (":" base-specifier-list)[opt]
base-specifier-list ->
base-specifier "..."[opt]
| base-specifier-list, base-specifier "..."[opt]
@@ -281,7 +274,8 @@ T = TypeVar('T')
goal: an unscoped enum or a scoped enum, optionally with the underlying
type specified
grammar:
("class" | "struct")[opt] visibility[opt] nested-name (":" type)[opt]
("class" | "struct")[opt] visibility[opt]
attribute-specifier-seq[opt] nested-name (":" type)[opt]
enumerator_object:
goal: an element in a scoped or unscoped enum. The name should be
injected according to the scopedness.
@@ -535,7 +529,8 @@ _id_operator_v2 = {
'->': 'pt',
'()': 'cl',
'[]': 'ix',
'.*': 'ds' # this one is not overloadable, but we need it for expressions
'.*': 'ds', # this one is not overloadable, but we need it for expressions
'?': 'qu',
}
_id_operator_unary_v2 = {
'++': 'pp_',
@@ -1524,6 +1519,44 @@ class ASTBinOpExpr(ASTExpression):
self.exprs[i].describe_signature(signode, mode, env, symbol)
class ASTConditionalExpr(ASTExpression):
def __init__(self, ifExpr: ASTExpression, thenExpr: ASTExpression,
elseExpr: ASTExpression):
self.ifExpr = ifExpr
self.thenExpr = thenExpr
self.elseExpr = elseExpr
def _stringify(self, transform: StringifyTransform) -> str:
res = []
res.append(transform(self.ifExpr))
res.append(' ? ')
res.append(transform(self.thenExpr))
res.append(' : ')
res.append(transform(self.elseExpr))
return ''.join(res)
def get_id(self, version: int) -> str:
assert version >= 2
res = []
res.append(_id_operator_v2['?'])
res.append(self.ifExpr.get_id(version))
res.append(self.thenExpr.get_id(version))
res.append(self.elseExpr.get_id(version))
return ''.join(res)
def describe_signature(self, signode: TextElement, mode: str,
env: "BuildEnvironment", symbol: "Symbol") -> None:
self.ifExpr.describe_signature(signode, mode, env, symbol)
signode += addnodes.desc_sig_space()
signode += addnodes.desc_sig_operator('?', '?')
signode += addnodes.desc_sig_space()
self.thenExpr.describe_signature(signode, mode, env, symbol)
signode += addnodes.desc_sig_space()
signode += addnodes.desc_sig_operator(':', ':')
signode += addnodes.desc_sig_space()
self.elseExpr.describe_signature(signode, mode, env, symbol)
class ASTBracedInitList(ASTBase):
def __init__(self, exprs: List[Union[ASTExpression, "ASTBracedInitList"]],
trailingComma: bool) -> None:
@@ -1556,42 +1589,39 @@ class ASTBracedInitList(ASTBase):
class ASTAssignmentExpr(ASTExpression):
def __init__(self, exprs: List[Union[ASTExpression, ASTBracedInitList]], ops: List[str]):
assert len(exprs) > 0
assert len(exprs) == len(ops) + 1
self.exprs = exprs
self.ops = ops
def __init__(self, leftExpr: ASTExpression, op: str,
rightExpr: Union[ASTExpression, ASTBracedInitList]):
self.leftExpr = leftExpr
self.op = op
self.rightExpr = rightExpr
def _stringify(self, transform: StringifyTransform) -> str:
res = []
res.append(transform(self.exprs[0]))
for i in range(1, len(self.exprs)):
res.append(' ')
res.append(self.ops[i - 1])
res.append(' ')
res.append(transform(self.exprs[i]))
res.append(transform(self.leftExpr))
res.append(' ')
res.append(self.op)
res.append(' ')
res.append(transform(self.rightExpr))
return ''.join(res)
def get_id(self, version: int) -> str:
# we end up generating the ID from left to right, instead of right to left
res = []
for i in range(len(self.ops)):
res.append(_id_operator_v2[self.ops[i]])
res.append(self.exprs[i].get_id(version))
res.append(self.exprs[-1].get_id(version))
res.append(_id_operator_v2[self.op])
res.append(self.leftExpr.get_id(version))
res.append(self.rightExpr.get_id(version))
return ''.join(res)
def describe_signature(self, signode: TextElement, mode: str,
env: "BuildEnvironment", symbol: "Symbol") -> None:
self.exprs[0].describe_signature(signode, mode, env, symbol)
for i in range(1, len(self.exprs)):
signode += addnodes.desc_sig_space()
op = self.ops[i - 1]
if ord(op[0]) >= ord('a') and ord(op[0]) <= ord('z'):
signode += addnodes.desc_sig_keyword(op, op)
else:
signode += addnodes.desc_sig_operator(op, op)
signode += addnodes.desc_sig_space()
self.exprs[i].describe_signature(signode, mode, env, symbol)
self.leftExpr.describe_signature(signode, mode, env, symbol)
signode += addnodes.desc_sig_space()
if ord(self.op[0]) >= ord('a') and ord(self.op[0]) <= ord('z'):
signode += addnodes.desc_sig_keyword(self.op, self.op)
else:
signode += addnodes.desc_sig_operator(self.op, self.op)
signode += addnodes.desc_sig_space()
self.rightExpr.describe_signature(signode, mode, env, symbol)
class ASTCommaExpr(ASTExpression):
@@ -2018,7 +2048,7 @@ class ASTParametersQualifiers(ASTBase):
def __init__(self, args: List[ASTFunctionParameter], volatile: bool, const: bool,
refQual: Optional[str], exceptionSpec: ASTNoexceptSpec,
trailingReturn: "ASTType",
override: bool, final: bool, attrs: List[ASTAttribute],
override: bool, final: bool, attrs: ASTAttributeList,
initializer: Optional[str]) -> None:
self.args = args
self.volatile = volatile
@@ -2088,9 +2118,9 @@ class ASTParametersQualifiers(ASTBase):
res.append(' final')
if self.override:
res.append(' override')
for attr in self.attrs:
if len(self.attrs) != 0:
res.append(' ')
res.append(transform(attr))
res.append(transform(self.attrs))
if self.initializer:
res.append(' = ')
res.append(self.initializer)
@@ -2141,9 +2171,9 @@ class ASTParametersQualifiers(ASTBase):
_add_anno(signode, 'final')
if self.override:
_add_anno(signode, 'override')
for attr in self.attrs:
if len(self.attrs) != 0:
signode += addnodes.desc_sig_space()
attr.describe_signature(signode)
self.attrs.describe_signature(signode)
if self.initializer:
signode += addnodes.desc_sig_space()
signode += addnodes.desc_sig_punctuation('=', '=')
@@ -2181,7 +2211,7 @@ class ASTDeclSpecsSimple(ASTBase):
explicitSpec: Optional[ASTExplicitSpec],
consteval: bool, constexpr: bool, constinit: bool,
volatile: bool, const: bool, friend: bool,
attrs: List[ASTAttribute]) -> None:
attrs: ASTAttributeList) -> None:
self.storage = storage
self.threadLocal = threadLocal
self.inline = inline
@@ -2213,7 +2243,8 @@ class ASTDeclSpecsSimple(ASTBase):
def _stringify(self, transform: StringifyTransform) -> str:
res: List[str] = []
res.extend(transform(attr) for attr in self.attrs)
if len(self.attrs) != 0:
res.append(transform(self.attrs))
if self.storage:
res.append(self.storage)
if self.threadLocal:
@@ -2240,12 +2271,8 @@ class ASTDeclSpecsSimple(ASTBase):
def describe_signature(self, signode: TextElement,
env: "BuildEnvironment", symbol: "Symbol") -> None:
addSpace = False
for attr in self.attrs:
if addSpace:
signode += addnodes.desc_sig_space()
addSpace = True
attr.describe_signature(signode)
self.attrs.describe_signature(signode)
addSpace = len(self.attrs) != 0
def _add(signode: TextElement, text: str) -> bool:
if addSpace:
@@ -2562,7 +2589,7 @@ class ASTDeclaratorNameBitField(ASTDeclarator):
class ASTDeclaratorPtr(ASTDeclarator):
def __init__(self, next: ASTDeclarator, volatile: bool, const: bool,
attrs: List[ASTAttribute]) -> None:
attrs: ASTAttributeList) -> None:
assert next
self.next = next
self.volatile = volatile
@@ -2590,9 +2617,8 @@ class ASTDeclaratorPtr(ASTDeclarator):
def _stringify(self, transform: StringifyTransform) -> str:
res = ['*']
for a in self.attrs:
res.append(transform(a))
if len(self.attrs) > 0 and (self.volatile or self.const):
res.append(transform(self.attrs))
if len(self.attrs) != 0 and (self.volatile or self.const):
res.append(' ')
if self.volatile:
res.append('volatile')
@@ -2647,9 +2673,8 @@ class ASTDeclaratorPtr(ASTDeclarator):
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
signode += addnodes.desc_sig_punctuation('*', '*')
for a in self.attrs:
a.describe_signature(signode)
if len(self.attrs) > 0 and (self.volatile or self.const):
self.attrs.describe_signature(signode)
if len(self.attrs) != 0 and (self.volatile or self.const):
signode += addnodes.desc_sig_space()
def _add_anno(signode: TextElement, text: str) -> None:
@@ -2667,7 +2692,7 @@ class ASTDeclaratorPtr(ASTDeclarator):
class ASTDeclaratorRef(ASTDeclarator):
def __init__(self, next: ASTDeclarator, attrs: List[ASTAttribute]) -> None:
def __init__(self, next: ASTDeclarator, attrs: ASTAttributeList) -> None:
assert next
self.next = next
self.attrs = attrs
@@ -2697,9 +2722,8 @@ class ASTDeclaratorRef(ASTDeclarator):
def _stringify(self, transform: StringifyTransform) -> str:
res = ['&']
for a in self.attrs:
res.append(transform(a))
if len(self.attrs) > 0 and self.next.require_space_after_declSpecs():
res.append(transform(self.attrs))
if len(self.attrs) != 0 and self.next.require_space_after_declSpecs():
res.append(' ')
res.append(transform(self.next))
return ''.join(res)
@@ -2728,8 +2752,7 @@ class ASTDeclaratorRef(ASTDeclarator):
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
signode += addnodes.desc_sig_punctuation('&', '&')
for a in self.attrs:
a.describe_signature(signode)
self.attrs.describe_signature(signode)
if len(self.attrs) > 0 and self.next.require_space_after_declSpecs():
signode += addnodes.desc_sig_space()
self.next.describe_signature(signode, mode, env, symbol)
@@ -3318,16 +3341,21 @@ class ASTBaseClass(ASTBase):
class ASTClass(ASTBase):
def __init__(self, name: ASTNestedName, final: bool, bases: List[ASTBaseClass]) -> None:
def __init__(self, name: ASTNestedName, final: bool, bases: List[ASTBaseClass],
attrs: ASTAttributeList) -> None:
self.name = name
self.final = final
self.bases = bases
self.attrs = attrs
def get_id(self, version: int, objectType: str, symbol: "Symbol") -> str:
return symbol.get_full_nested_name().get_id(version)
def _stringify(self, transform: StringifyTransform) -> str:
res = []
res.append(transform(self.attrs))
if len(self.attrs) != 0:
res.append(' ')
res.append(transform(self.name))
if self.final:
res.append(' final')
@@ -3344,6 +3372,9 @@ class ASTClass(ASTBase):
def describe_signature(self, signode: TextElement, mode: str,
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
self.attrs.describe_signature(signode)
if len(self.attrs) != 0:
signode += addnodes.desc_sig_space()
self.name.describe_signature(signode, mode, env, symbol=symbol)
if self.final:
signode += addnodes.desc_sig_space()
@@ -3361,8 +3392,9 @@ class ASTClass(ASTBase):
class ASTUnion(ASTBase):
def __init__(self, name: ASTNestedName) -> None:
def __init__(self, name: ASTNestedName, attrs: ASTAttributeList) -> None:
self.name = name
self.attrs = attrs
def get_id(self, version: int, objectType: str, symbol: "Symbol") -> str:
if version == 1:
@@ -3370,20 +3402,29 @@ class ASTUnion(ASTBase):
return symbol.get_full_nested_name().get_id(version)
def _stringify(self, transform: StringifyTransform) -> str:
return transform(self.name)
res = []
res.append(transform(self.attrs))
if len(self.attrs) != 0:
res.append(' ')
res.append(transform(self.name))
return ''.join(res)
def describe_signature(self, signode: TextElement, mode: str,
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
self.attrs.describe_signature(signode)
if len(self.attrs) != 0:
signode += addnodes.desc_sig_space()
self.name.describe_signature(signode, mode, env, symbol=symbol)
class ASTEnum(ASTBase):
def __init__(self, name: ASTNestedName, scoped: str,
underlyingType: ASTType) -> None:
def __init__(self, name: ASTNestedName, scoped: str, underlyingType: ASTType,
attrs: ASTAttributeList) -> None:
self.name = name
self.scoped = scoped
self.underlyingType = underlyingType
self.attrs = attrs
def get_id(self, version: int, objectType: str, symbol: "Symbol") -> str:
if version == 1:
@@ -3395,6 +3436,9 @@ class ASTEnum(ASTBase):
if self.scoped:
res.append(self.scoped)
res.append(' ')
res.append(transform(self.attrs))
if len(self.attrs) != 0:
res.append(' ')
res.append(transform(self.name))
if self.underlyingType:
res.append(' : ')
@@ -3405,6 +3449,9 @@ class ASTEnum(ASTBase):
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
# self.scoped has been done by the CPPEnumObject
self.attrs.describe_signature(signode)
if len(self.attrs) != 0:
signode += addnodes.desc_sig_space()
self.name.describe_signature(signode, mode, env, symbol=symbol)
if self.underlyingType:
signode += addnodes.desc_sig_space()
@@ -3415,9 +3462,11 @@ class ASTEnum(ASTBase):
class ASTEnumerator(ASTBase):
def __init__(self, name: ASTNestedName, init: ASTInitializer) -> None:
def __init__(self, name: ASTNestedName, init: Optional[ASTInitializer],
attrs: ASTAttributeList) -> None:
self.name = name
self.init = init
self.attrs = attrs
def get_id(self, version: int, objectType: str, symbol: "Symbol") -> str:
if version == 1:
@@ -3427,6 +3476,9 @@ class ASTEnumerator(ASTBase):
def _stringify(self, transform: StringifyTransform) -> str:
res = []
res.append(transform(self.name))
if len(self.attrs) != 0:
res.append(' ')
res.append(transform(self.attrs))
if self.init:
res.append(transform(self.init))
return ''.join(res)
@@ -3435,6 +3487,9 @@ class ASTEnumerator(ASTBase):
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
self.name.describe_signature(signode, mode, env, symbol)
if len(self.attrs) != 0:
signode += addnodes.desc_sig_space()
self.attrs.describe_signature(signode)
if self.init:
self.init.describe_signature(signode, 'markType', env, symbol)
@@ -5598,50 +5653,60 @@ class DefinitionParser(BaseParser):
return ASTBinOpExpr(exprs, ops)
return _parse_bin_op_expr(self, 0, inTemplate=inTemplate)
def _parse_conditional_expression_tail(self, orExprHead: Any) -> None:
def _parse_conditional_expression_tail(self, orExprHead: ASTExpression,
inTemplate: bool) -> Optional[ASTConditionalExpr]:
# Consumes the orExprHead on success.
# -> "?" expression ":" assignment-expression
return None
self.skip_ws()
if not self.skip_string("?"):
return None
thenExpr = self._parse_expression()
self.skip_ws()
if not self.skip_string(":"):
self.fail('Expected ":" after then-expression in conditional expression.')
elseExpr = self._parse_assignment_expression(inTemplate)
return ASTConditionalExpr(orExprHead, thenExpr, elseExpr)
def _parse_assignment_expression(self, inTemplate: bool) -> ASTExpression:
# -> conditional-expression
# | logical-or-expression assignment-operator initializer-clause
# | throw-expression
# TODO: parse throw-expression: "throw" assignment-expression [opt]
# if not a throw expression, then:
# -> conditional-expression ->
# | yield-expression -> "co_yield" assignment-expression
# | "co_yield" braced-init-list
# | throw-expression -> "throw" assignment-expression[opt]
# TODO: yield-expression
# TODO: throw-expression
# Now we have (after expanding conditional-expression:
# logical-or-expression
# | logical-or-expression "?" expression ":" assignment-expression
# | logical-or-expression assignment-operator initializer-clause
exprs: List[Union[ASTExpression, ASTBracedInitList]] = []
ops = []
orExpr = self._parse_logical_or_expression(inTemplate=inTemplate)
exprs.append(orExpr)
# TODO: handle ternary with _parse_conditional_expression_tail
while True:
oneMore = False
self.skip_ws()
for op in _expression_assignment_ops:
if op[0] in 'anox':
if not self.skip_word(op):
continue
else:
if not self.skip_string(op):
continue
expr = self._parse_initializer_clause()
exprs.append(expr)
ops.append(op)
oneMore = True
if not oneMore:
break
if len(ops) == 0:
return orExpr
else:
return ASTAssignmentExpr(exprs, ops)
leftExpr = self._parse_logical_or_expression(inTemplate=inTemplate)
# the ternary operator
condExpr = self._parse_conditional_expression_tail(leftExpr, inTemplate)
if condExpr is not None:
return condExpr
# and actual assignment
for op in _expression_assignment_ops:
if op[0] in 'anox':
if not self.skip_word(op):
continue
else:
if not self.skip_string(op):
continue
rightExpr = self._parse_initializer_clause()
return ASTAssignmentExpr(leftExpr, op, rightExpr)
# just a logical-or-expression
return leftExpr
def _parse_constant_expression(self, inTemplate: bool) -> ASTExpression:
# -> conditional-expression
# -> conditional-expression ->
# logical-or-expression
# | logical-or-expression "?" expression ":" assignment-expression
orExpr = self._parse_logical_or_expression(inTemplate=inTemplate)
# TODO: use _parse_conditional_expression_tail
condExpr = self._parse_conditional_expression_tail(orExpr, inTemplate)
if condExpr is not None:
return condExpr
return orExpr
def _parse_expression(self) -> ASTExpression:
@@ -6057,12 +6122,7 @@ class DefinitionParser(BaseParser):
override = self.skip_word_and_ws(
'override') # they can be permuted
attrs = []
while True:
attr = self._parse_attribute()
if attr is None:
break
attrs.append(attr)
attrs = self._parse_attribute_list()
self.skip_ws()
initializer = None
@@ -6174,7 +6234,7 @@ class DefinitionParser(BaseParser):
break
return ASTDeclSpecsSimple(storage, threadLocal, inline, virtual,
explicitSpec, consteval, constexpr, constinit,
volatile, const, friend, attrs)
volatile, const, friend, ASTAttributeList(attrs))
def _parse_decl_specs(self, outer: str, typed: bool = True) -> ASTDeclSpecs:
if outer:
@@ -6271,7 +6331,7 @@ class DefinitionParser(BaseParser):
self.skip_ws()
volatile = False
const = False
attrs = []
attrList = []
while 1:
if not volatile:
volatile = self.skip_word_and_ws('volatile')
@@ -6283,19 +6343,15 @@ class DefinitionParser(BaseParser):
continue
attr = self._parse_attribute()
if attr is not None:
attrs.append(attr)
attrList.append(attr)
continue
break
next = self._parse_declarator(named, paramMode, typed)
return ASTDeclaratorPtr(next=next, volatile=volatile, const=const, attrs=attrs)
return ASTDeclaratorPtr(next=next, volatile=volatile, const=const,
attrs=ASTAttributeList(attrList))
# TODO: shouldn't we parse an R-value ref here first?
if typed and self.skip_string("&"):
attrs = []
while 1:
attr = self._parse_attribute()
if attr is None:
break
attrs.append(attr)
attrs = self._parse_attribute_list()
next = self._parse_declarator(named, paramMode, typed)
return ASTDeclaratorRef(next=next, attrs=attrs)
if typed and self.skip_string("..."):
@@ -6567,6 +6623,7 @@ class DefinitionParser(BaseParser):
return ASTConcept(nestedName, initializer)
def _parse_class(self) -> ASTClass:
attrs = self._parse_attribute_list()
name = self._parse_nested_name()
self.skip_ws()
final = self.skip_word_and_ws('final')
@@ -6594,24 +6651,26 @@ class DefinitionParser(BaseParser):
continue
else:
break
return ASTClass(name, final, bases)
return ASTClass(name, final, bases, attrs)
def _parse_union(self) -> ASTUnion:
attrs = self._parse_attribute_list()
name = self._parse_nested_name()
return ASTUnion(name)
return ASTUnion(name, attrs)
def _parse_enum(self) -> ASTEnum:
scoped = None # is set by CPPEnumObject
self.skip_ws()
attrs = self._parse_attribute_list()
name = self._parse_nested_name()
self.skip_ws()
underlyingType = None
if self.skip_string(':'):
underlyingType = self._parse_type(named=False)
return ASTEnum(name, scoped, underlyingType)
return ASTEnum(name, scoped, underlyingType, attrs)
def _parse_enumerator(self) -> ASTEnumerator:
name = self._parse_nested_name()
attrs = self._parse_attribute_list()
self.skip_ws()
init = None
if self.skip_string('='):
@@ -6621,7 +6680,7 @@ class DefinitionParser(BaseParser):
return self._parse_constant_expression(inTemplate=False)
initVal = self._parse_expression_fallback([], parser)
init = ASTInitializer(initVal)
return ASTEnumerator(name, init)
return ASTEnumerator(name, init, attrs)
# ==========================================================================
@@ -7992,7 +8051,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
return {
'version': 'builtin',
'env_version': 4,
'env_version': 6,
'parallel_read_safe': True,
'parallel_write_safe': True,
}

12
sphinx/domains/index.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.index
~~~~~~~~~~~~~~~~~~~~
The index domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The index domain."""
from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Tuple
@@ -110,7 +102,7 @@ class IndexRole(ReferenceRole):
index = addnodes.index(entries=entries)
target = nodes.target('', '', ids=[target_id])
text = nodes.Text(title, title)
text = nodes.Text(title)
self.set_source_info(index)
return [index, target, text], []

24
sphinx/domains/javascript.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.javascript
~~~~~~~~~~~~~~~~~~~~~~~~~
The JavaScript domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The JavaScript domain."""
from typing import Any, Dict, Iterator, List, Optional, Tuple, cast
@@ -122,13 +114,6 @@ class JSObject(ObjectDescription[Tuple[str, str]]):
fullname = (mod_name + '.' if mod_name else '') + name_obj[0]
node_id = make_id(self.env, self.state.document, '', fullname)
signode['ids'].append(node_id)
# Assign old styled node_id not to break old hyperlinks (if possible)
# Note: Will be removed in Sphinx-5.0 (RemovedInSphinx50Warning)
old_node_id = self.make_old_id(fullname)
if old_node_id not in self.state.document.ids and old_node_id not in signode['ids']:
signode['ids'].append(old_node_id)
self.state.document.note_explicit_target(signode)
domain = cast(JavaScriptDomain, self.env.get_domain('js'))
@@ -288,13 +273,6 @@ class JSModule(SphinxDirective):
location=(self.env.docname, self.lineno))
target = nodes.target('', '', ids=[node_id], ismod=True)
# Assign old styled node_id not to break old hyperlinks (if possible)
# Note: Will be removed in Sphinx-5.0 (RemovedInSphinx50Warning)
old_node_id = self.make_old_id(mod_name)
if old_node_id not in self.state.document.ids and old_node_id not in target['ids']:
target['ids'].append(old_node_id)
self.state.document.note_explicit_target(target)
ret.append(target)
indextext = _('%s (module)') % mod_name

10
sphinx/domains/math.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.math
~~~~~~~~~~~~~~~~~~~
The math domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The math domain."""
from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Tuple

25
sphinx/domains/python.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.python
~~~~~~~~~~~~~~~~~~~~~
The Python domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The Python domain."""
import builtins
import inspect
@@ -573,12 +565,6 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
fullname = (modname + '.' if modname else '') + name_cls[0]
node_id = make_id(self.env, self.state.document, '', fullname)
signode['ids'].append(node_id)
# Assign old styled node_id(fullname) not to break old hyperlinks (if possible)
# Note: Will removed in Sphinx-5.0 (RemovedInSphinx50Warning)
if node_id != fullname and fullname not in self.state.document.ids:
signode['ids'].append(fullname)
self.state.document.note_explicit_target(signode)
domain = cast(PythonDomain, self.env.get_domain('py'))
@@ -1002,13 +988,6 @@ class PyModule(SphinxDirective):
node_id = make_id(self.env, self.state.document, 'module', modname)
target = nodes.target('', '', ids=[node_id], ismod=True)
self.set_source_info(target)
# Assign old styled node_id not to break old hyperlinks (if possible)
# Note: Will removed in Sphinx-5.0 (RemovedInSphinx50Warning)
old_node_id = self.make_old_id(modname)
if node_id != old_node_id and old_node_id not in self.state.document.ids:
target['ids'].append(old_node_id)
self.state.document.note_explicit_target(target)
domain.note_module(modname,
@@ -1447,7 +1426,7 @@ def builtin_resolver(app: Sphinx, env: BuildEnvironment,
if s.startswith('typing.'):
s = s.split('.', 1)[1]
return s in typing.__all__ # type: ignore
return s in typing.__all__
if node.get('refdomain') != 'py':
return None

24
sphinx/domains/rst.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.rst
~~~~~~~~~~~~~~~~~~
The reStructuredText domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The reStructuredText domain."""
import re
from typing import Any, Dict, Iterator, List, Optional, Tuple, cast
@@ -40,13 +32,6 @@ class ReSTMarkup(ObjectDescription[str]):
def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:
node_id = make_id(self.env, self.state.document, self.objtype, name)
signode['ids'].append(node_id)
# Assign old styled node_id not to break old hyperlinks (if possible)
# Note: Will be removed in Sphinx-5.0 (RemovedInSphinx50Warning)
old_node_id = self.make_old_id(name)
if old_node_id not in self.state.document.ids and old_node_id not in signode['ids']:
signode['ids'].append(old_node_id)
self.state.document.note_explicit_target(signode)
domain = cast(ReSTDomain, self.env.get_domain('rst'))
@@ -150,13 +135,6 @@ class ReSTDirectiveOption(ReSTMarkup):
node_id = make_id(self.env, self.state.document, prefix, name)
signode['ids'].append(node_id)
# Assign old styled node_id not to break old hyperlinks (if possible)
# Note: Will be removed in Sphinx-5.0 (RemovedInSphinx50Warning)
old_node_id = self.make_old_id(name)
if old_node_id not in self.state.document.ids and old_node_id not in signode['ids']:
signode['ids'].append(old_node_id)
self.state.document.note_explicit_target(signode)
domain.note_object(self.objtype, objname, node_id, location=signode)

44
sphinx/domains/std.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.domains.std
~~~~~~~~~~~~~~~~~~
The standard domain.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The standard domain."""
import re
from copy import copy
@@ -63,13 +55,6 @@ class GenericObject(ObjectDescription[str]):
def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:
node_id = make_id(self.env, self.state.document, self.objtype, name)
signode['ids'].append(node_id)
# Assign old styled node_id not to break old hyperlinks (if possible)
# Note: Will be removed in Sphinx-5.0 (RemovedInSphinx50Warning)
old_node_id = self.make_old_id(name)
if old_node_id not in self.state.document.ids and old_node_id not in signode['ids']:
signode['ids'].append(old_node_id)
self.state.document.note_explicit_target(signode)
if self.indextemplate:
@@ -137,13 +122,6 @@ class Target(SphinxDirective):
node_id = make_id(self.env, self.state.document, self.name, fullname)
node = nodes.target('', '', ids=[node_id])
self.set_source_info(node)
# Assign old styled node_id not to break old hyperlinks (if possible)
# Note: Will be removed in Sphinx-5.0 (RemovedInSphinx50Warning)
old_node_id = self.make_old_id(fullname)
if old_node_id not in self.state.document.ids and old_node_id not in node['ids']:
node['ids'].append(old_node_id)
self.state.document.note_explicit_target(node)
ret: List[Node] = [node]
if self.indextemplate:
@@ -438,7 +416,7 @@ def token_xrefs(text: str, productionGroup: str = '') -> List[Node]:
for m in token_re.finditer(text):
if m.start() > pos:
txt = text[pos:m.start()]
retnodes.append(nodes.Text(txt, txt))
retnodes.append(nodes.Text(txt))
token = m.group(1)
if ':' in token:
if token[0] == '~':
@@ -459,7 +437,7 @@ def token_xrefs(text: str, productionGroup: str = '') -> List[Node]:
retnodes.append(refnode)
pos = m.end()
if pos < len(text):
retnodes.append(nodes.Text(text[pos:], text[pos:]))
retnodes.append(nodes.Text(text[pos:]))
return retnodes
@@ -500,14 +478,6 @@ class ProductionList(SphinxDirective):
prefix = 'grammar-token-%s' % productionGroup
node_id = make_id(self.env, self.state.document, prefix, name)
subnode['ids'].append(node_id)
# Assign old styled node_id not to break old hyperlinks (if possible)
# Note: Will be removed in Sphinx-5.0 (RemovedInSphinx50Warning)
old_node_id = self.make_old_id(name)
if (old_node_id not in self.state.document.ids and
old_node_id not in subnode['ids']):
subnode['ids'].append(old_node_id)
self.state.document.note_implicit_target(subnode, subnode)
if len(productionGroup) != 0:
@@ -755,11 +725,10 @@ class StandardDomain(Domain):
sectname = clean_astext(title)
elif node.tagname == 'rubric':
sectname = clean_astext(node)
elif node.tagname == 'target' and len(node) > 0:
# inline target (ex: blah _`blah` blah)
sectname = clean_astext(node)
elif self.is_enumerable_node(node):
sectname = self.get_numfig_title(node)
if not sectname:
continue
else:
toctree = next(node.findall(addnodes.toctree), None)
if toctree and toctree.get('caption'):
@@ -767,8 +736,7 @@ class StandardDomain(Domain):
else:
# anonymous-only labels
continue
if sectname:
self.labels[name] = docname, labelid, sectname
self.labels[name] = docname, labelid, sectname
def add_program_option(self, program: str, name: str, docname: str, labelid: str) -> None:
self.progoptions[program, name] = (docname, labelid)

17
sphinx/environment/__init__.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment
~~~~~~~~~~~~~~~~~~
Global creation environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Global creation environment."""
import os
import pickle
@@ -18,6 +10,7 @@ from os import path
from typing import (TYPE_CHECKING, Any, Callable, Dict, Generator, Iterator, List, Optional,
Set, Tuple, Union)
import docutils
from docutils import nodes
from docutils.nodes import Node
@@ -46,10 +39,10 @@ logger = logging.getLogger(__name__)
default_settings: Dict[str, Any] = {
'auto_id_prefix': 'id',
'embed_images': False,
'image_loading': 'link',
'embed_stylesheet': False,
'cloak_email_addresses': True,
'pep_base_url': 'https://www.python.org/dev/peps/',
'pep_base_url': 'https://peps.python.org/',
'pep_references': None,
'rfc_base_url': 'https://datatracker.ietf.org/doc/html/',
'rfc_references': None,
@@ -61,6 +54,8 @@ default_settings: Dict[str, Any] = {
'file_insertion_enabled': True,
'smartquotes_locales': [],
}
if docutils.__version_info__[:2] <= (0, 17):
default_settings['embed_images'] = False
# This is increased every time an environment attribute is added
# or changed to properly invalidate pickle files.

10
sphinx/environment/adapters/__init__.py
View File

@@ -1,9 +1 @@
"""
sphinx.environment.adapters
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sphinx environment adapters
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Sphinx environment adapters"""

10
sphinx/environment/adapters/asset.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment.adapters.asset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Assets adapter for sphinx.environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Assets adapter for sphinx.environment."""
from sphinx.environment import BuildEnvironment

10
sphinx/environment/adapters/indexentries.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment.adapters.indexentries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Index entries adapters for sphinx.environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Index entries adapters for sphinx.environment."""
import re
import unicodedata

10
sphinx/environment/adapters/toctree.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment.adapters.toctree
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Toctree adapter for sphinx.environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Toctree adapter for sphinx.environment."""
from typing import TYPE_CHECKING, Any, Iterable, List, Optional, cast

10
sphinx/environment/collectors/__init__.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment.collectors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The data collector components for sphinx.environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The data collector components for sphinx.environment."""
from typing import TYPE_CHECKING, Dict, List, Optional, Set

10
sphinx/environment/collectors/asset.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment.collectors.asset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The image collector for sphinx.environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The image collector for sphinx.environment."""
import os
from glob import glob

10
sphinx/environment/collectors/dependencies.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment.collectors.dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The dependencies collector components for sphinx.environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The dependencies collector components for sphinx.environment."""
import os
from os import path

10
sphinx/environment/collectors/metadata.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment.collectors.metadata
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The metadata collector components for sphinx.environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The metadata collector components for sphinx.environment."""
from typing import Any, Dict, List, Set, cast

10
sphinx/environment/collectors/title.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment.collectors.title
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The title collector components for sphinx.environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""The title collector components for sphinx.environment."""
from typing import Any, Dict, Set

10
sphinx/environment/collectors/toctree.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.environment.collectors.toctree
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Toctree collector for sphinx.environment.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Toctree collector for sphinx.environment."""
from typing import Any, Dict, List, Set, Tuple, Type, TypeVar, cast

11
sphinx/errors.py
View File

@@ -1,13 +1,4 @@
"""
sphinx.errors
~~~~~~~~~~~~~
Contains SphinxError and a few subclasses (in an extra module to avoid
circular import problems).
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Contains SphinxError and a few subclasses."""
from typing import Any

11
sphinx/events.py
View File

@@ -1,13 +1,6 @@
"""
sphinx.events
~~~~~~~~~~~~~
"""Sphinx core events.
Sphinx core events.
Gracefully adapted from the TextPress system by Armin.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
Gracefully adapted from the TextPress system by Armin.
"""
from collections import defaultdict

10
sphinx/ext/__init__.py
View File

@@ -1,9 +1 @@
"""
sphinx.ext
~~~~~~~~~~
Contains Sphinx features not activated by default.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Contains Sphinx features not activated by default."""

20
sphinx/ext/apidoc.py
View File

@@ -1,17 +1,12 @@
"""
sphinx.ext.apidoc
~~~~~~~~~~~~~~~~~
"""Creates reST files corresponding to Python modules for code documentation.
Parses a directory tree looking for Python modules and packages and creates
ReST files appropriately to create code documentation with Sphinx. It also
creates a modules index (named modules.<suffix>).
Parses a directory tree looking for Python modules and packages and creates
ReST files appropriately to create code documentation with Sphinx. It also
creates a modules index (named modules.<suffix>).
This is derived from the "sphinx-autopackage" script, which is:
Copyright 2008 Société des arts technologiques (SAT),
https://sat.qc.ca/
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
This is derived from the "sphinx-autopackage" script, which is:
Copyright 2008 Société des arts technologiques (SAT),
https://sat.qc.ca/
"""
import argparse
@@ -122,6 +117,7 @@ def create_package_file(root: str, master_package: str, subroot: str, py_files:
submodules = [sub.split('.')[0] for sub in py_files
if not is_skipped_module(path.join(root, sub), opts, excludes) and
not is_initpy(sub)]
submodules = sorted(set(submodules))
submodules = [module_join(master_package, subroot, modname)
for modname in submodules]
options = copy(OPTIONS)

214
sphinx/ext/autodoc/__init__.py
View File

@@ -1,13 +1,8 @@
"""
sphinx.ext.autodoc
~~~~~~~~~~~~~~~~~~
"""Extension to create automatic documentation from code docstrings.
Automatically insert docstrings for functions, classes or whole modules into
the doctree, thus avoiding duplication between docstrings and documentation
for those who like elaborate docstrings.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
Automatically insert docstrings for functions, classes or whole modules into
the doctree, thus avoiding duplication between docstrings and documentation
for those who like elaborate docstrings.
"""
import re
@@ -22,7 +17,7 @@ from docutils.statemachine import StringList
import sphinx
from sphinx.application import Sphinx
from sphinx.config import ENUM, Config
from sphinx.deprecation import RemovedInSphinx50Warning, RemovedInSphinx60Warning
from sphinx.deprecation import RemovedInSphinx60Warning
from sphinx.environment import BuildEnvironment
from sphinx.ext.autodoc.importer import (get_class_members, get_object_members, import_module,
import_object)
@@ -98,15 +93,6 @@ def members_option(arg: Any) -> Union[object, List[str]]:
return [x.strip() for x in arg.split(',') if x.strip()]
def members_set_option(arg: Any) -> Union[object, Set[str]]:
"""Used to convert the :members: option to auto directives."""
warnings.warn("members_set_option() is deprecated.",
RemovedInSphinx50Warning, stacklevel=2)
if arg is None:
return ALL
return {x.strip() for x in arg.split(',') if x.strip()}
def exclude_members_option(arg: Any) -> Union[object, Set[str]]:
"""Used to convert the :exclude-members: option."""
if arg in (None, True):
@@ -114,16 +100,18 @@ def exclude_members_option(arg: Any) -> Union[object, Set[str]]:
return {x.strip() for x in arg.split(',') if x.strip()}
def inherited_members_option(arg: Any) -> Union[object, Set[str]]:
"""Used to convert the :members: option to auto directives."""
def inherited_members_option(arg: Any) -> Set[str]:
"""Used to convert the :inherited-members: option to auto directives."""
if arg in (None, True):
return 'object'
return {'object'}
elif arg:
return set(x.strip() for x in arg.split(','))
else:
return arg
return set()
def member_order_option(arg: Any) -> Optional[str]:
"""Used to convert the :members: option to auto directives."""
"""Used to convert the :member-order: option to auto directives."""
if arg in (None, True):
return None
elif arg in ('alphabetical', 'bysource', 'groupwise'):
@@ -158,23 +146,10 @@ def bool_option(arg: Any) -> bool:
return True
def merge_special_members_option(options: Dict) -> None:
"""Merge :special-members: option to :members: option."""
warnings.warn("merge_special_members_option() is deprecated.",
RemovedInSphinx50Warning, stacklevel=2)
if 'special-members' in options and options['special-members'] is not ALL:
if options.get('members') is ALL:
pass
elif options.get('members'):
for member in options['special-members']:
if member not in options['members']:
options['members'].append(member)
else:
options['members'] = options['special-members']
def merge_members_option(options: Dict) -> None:
"""Merge :*-members: option to the :members: option."""
"""Merge :private-members: and :special-members: options to the
:members: option.
"""
if options.get('members') is ALL:
# merging is not needed when members: ALL
return
@@ -552,21 +527,17 @@ class Documenter:
# etc. don't support a prepended module name
self.add_line(' :module: %s' % self.modname, sourcename)
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
def get_doc(self) -> Optional[List[List[str]]]:
"""Decode and return lines of the docstring(s) for the object.
When it returns None, autodoc-process-docstring will not be called for this
object.
"""
if ignore is not None:
warnings.warn("The 'ignore' argument to autodoc.%s.get_doc() is deprecated."
% self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
docstring = getdoc(self.object, self.get_attr, self.config.autodoc_inherit_docstrings,
self.parent, self.object_name)
if docstring:
tab_width = self.directive.state.document.settings.tab_width
return [prepare_docstring(docstring, ignore, tab_width)]
return [prepare_docstring(docstring, tab_width)]
return []
def process_doc(self, docstrings: List[List[str]]) -> Iterator[str]:
@@ -598,13 +569,9 @@ class Documenter:
else:
return 'docstring of %s' % fullname
def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
) -> None:
def add_content(self, more_content: Optional[StringList]) -> None:
"""Add content from docstrings, attribute documentation and user."""
if no_docstring:
warnings.warn("The 'no_docstring' argument to %s.add_content() is deprecated."
% self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
docstring = True
# set sourcename and add content from attribute documentation
sourcename = self.get_sourcename()
@@ -613,7 +580,7 @@ class Documenter:
if self.objpath:
key = ('.'.join(self.objpath[:-1]), self.objpath[-1])
if key in attr_docs:
no_docstring = True
docstring = False
# make a copy of docstring for attributes to avoid cache
# the change of autodoc-process-docstring event.
docstrings = [list(attr_docs[key])]
@@ -622,7 +589,7 @@ class Documenter:
self.add_line(line, sourcename, i)
# add content from docstrings
if not no_docstring:
if docstring:
docstrings = self.get_doc()
if docstrings is None:
# Do not call autodoc-process-docstring on get_doc() returns None.
@@ -685,9 +652,11 @@ class Documenter:
``autodoc-skip-member`` event.
"""
def is_filtered_inherited_member(name: str, obj: Any) -> bool:
inherited_members = self.options.inherited_members or set()
if inspect.isclass(self.object):
for cls in self.object.__mro__:
if cls.__name__ == self.options.inherited_members and cls != self.object:
if cls.__name__ in inherited_members and cls != self.object:
# given member is a member of specified *super class*
return True
elif name in cls.__dict__:
@@ -1229,7 +1198,7 @@ class DocstringSignatureMixin:
# re-prepare docstring to ignore more leading indentation
tab_width = self.directive.state.document.settings.tab_width # type: ignore
self._new_docstrings[i] = prepare_docstring('\n'.join(doclines[j + 1:]),
tabsize=tab_width)
tab_width)
if result is None:
# first signature
@@ -1244,10 +1213,10 @@ class DocstringSignatureMixin:
return result
def get_doc(self, ignore: int = None) -> List[List[str]]:
def get_doc(self) -> List[List[str]]:
if self._new_docstrings is not None:
return self._new_docstrings
return super().get_doc(ignore) # type: ignore
return super().get_doc() # type: ignore
def format_signature(self, **kwargs: Any) -> str:
if self.args is None and self.config.autodoc_docstring_signature: # type: ignore
@@ -1404,8 +1373,8 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ
except (AttributeError, TypeError):
# failed to update signature (ex. built-in or extension types)
return None
else:
return None
return func
class DecoratorDocumenter(FunctionDocumenter):
@@ -1585,6 +1554,20 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
return stringify_signature(sig, show_return_annotation=False, **kwargs)
def _find_signature(self) -> Tuple[str, str]:
result = super()._find_signature()
if result is not None:
# Strip a return value from signature of constructor in docstring (first entry)
result = (result[0], None)
for i, sig in enumerate(self._signatures):
if sig.endswith(' -> None'):
# Strip a return value from signatures of constructor in docstring (subsequent
# entries)
self._signatures[i] = sig[:-8]
return result
def format_signature(self, **kwargs: Any) -> str:
if self.doc_as_attr:
return ''
@@ -1666,7 +1649,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
if not self.doc_as_attr and self.options.show_inheritance:
if inspect.getorigbases(self.object):
# A subclass of generic types
# refs: PEP-560 <https://www.python.org/dev/peps/pep-0560/>
# refs: PEP-560 <https://peps.python.org/pep-0560/>
bases = list(self.object.__orig_bases__)
elif hasattr(self.object, '__bases__') and len(self.object.__bases__):
# A normal class
@@ -1705,7 +1688,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
else:
return False, [m for m in members.values() if m.class_ == self.object]
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
def get_doc(self) -> Optional[List[List[str]]]:
if self.doc_as_attr:
# Don't show the docstring of the class when it is an alias.
comment = self.get_variable_comment()
@@ -1755,7 +1738,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
docstrings.append(initdocstring)
tab_width = self.directive.state.document.settings.tab_width
return [prepare_docstring(docstring, ignore, tab_width) for docstring in docstrings]
return [prepare_docstring(docstring, tab_width) for docstring in docstrings]
def get_variable_comment(self) -> Optional[List[str]]:
try:
@@ -1769,8 +1752,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
except PycodeError:
return None
def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
) -> None:
def add_content(self, more_content: Optional[StringList]) -> None:
if self.doc_as_attr and self.modname != self.get_real_modname():
try:
# override analyzer to obtain doccomment around its definition.
@@ -1902,12 +1884,7 @@ class TypeVarMixin(DataDocumenterMixinBase):
return (isinstance(self.object, TypeVar) or
super().should_suppress_directive_header())
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
if ignore is not None:
warnings.warn("The 'ignore' argument to autodoc.%s.get_doc() is deprecated."
% self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
def get_doc(self) -> Optional[List[List[str]]]:
if isinstance(self.object, TypeVar):
if self.object.__doc__ != TypeVar.__doc__:
return super().get_doc() # type: ignore
@@ -1972,11 +1949,11 @@ class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
return (self.object is UNINITIALIZED_ATTR or
super().should_suppress_value_header())
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
def get_doc(self) -> Optional[List[List[str]]]:
if self.object is UNINITIALIZED_ATTR:
return []
else:
return super().get_doc(ignore) # type: ignore
return super().get_doc() # type: ignore
class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
@@ -2074,16 +2051,15 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
return None
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
def get_doc(self) -> Optional[List[List[str]]]:
# Check the variable has a docstring-comment
comment = self.get_module_comment(self.objpath[-1])
if comment:
return [comment]
else:
return super().get_doc(ignore)
return super().get_doc()
def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
) -> None:
def add_content(self, more_content: Optional[StringList]) -> None:
# Disable analyzing variable comment on Documenter.add_content() to control it on
# DataDocumenter.add_content()
self.analyzer = None
@@ -2092,7 +2068,7 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
more_content = StringList()
self.update_content(more_content)
super().add_content(more_content, no_docstring=no_docstring)
super().add_content(more_content)
class NewTypeDataDocumenter(DataDocumenter):
@@ -2286,10 +2262,10 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
except (AttributeError, TypeError):
# failed to update signature (ex. built-in or extension types)
return None
else:
return None
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
return func
def get_doc(self) -> Optional[List[List[str]]]:
if self._new_docstrings is not None:
# docstring already returned previously, then modified by
# `DocstringSignatureMixin`. Just return the previously-computed
@@ -2348,13 +2324,13 @@ class NonDataDescriptorMixin(DataDocumenterMixinBase):
return (not getattr(self, 'non_data_descriptor', False) or
super().should_suppress_directive_header())
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
def get_doc(self) -> Optional[List[List[str]]]:
if getattr(self, 'non_data_descriptor', False):
# the docstring of non datadescriptor is very probably the wrong thing
# to display
return None
else:
return super().get_doc(ignore) # type: ignore
return super().get_doc() # type: ignore
class SlotsMixin(DataDocumenterMixinBase):
@@ -2386,7 +2362,7 @@ class SlotsMixin(DataDocumenterMixinBase):
else:
return super().should_suppress_value_header()
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
def get_doc(self) -> Optional[List[List[str]]]:
if self.object is SLOTSATTR:
try:
__slots__ = inspect.getslots(self.parent)
@@ -2400,7 +2376,7 @@ class SlotsMixin(DataDocumenterMixinBase):
(self.parent.__qualname__, exc), type='autodoc')
return []
else:
return super().get_doc(ignore) # type: ignore
return super().get_doc() # type: ignore
@property
def _datadescriptor(self) -> bool:
@@ -2484,12 +2460,12 @@ class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
return (self.object is self.RUNTIME_INSTANCE_ATTRIBUTE or
super().should_suppress_value_header())
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
def get_doc(self) -> Optional[List[List[str]]]:
if (self.object is self.RUNTIME_INSTANCE_ATTRIBUTE and
self.is_runtime_instance_attribute_not_commented(self.parent)):
return None
else:
return super().get_doc(ignore) # type: ignore
return super().get_doc() # type: ignore
class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
@@ -2540,11 +2516,11 @@ class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
return (self.object is UNINITIALIZED_ATTR or
super().should_suppress_value_header())
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
def get_doc(self) -> Optional[List[List[str]]]:
if self.object is UNINITIALIZED_ATTR:
return None
else:
return super().get_doc(ignore) # type: ignore
return super().get_doc() # type: ignore
class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type: ignore
@@ -2583,27 +2559,6 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
def document_members(self, all_members: bool = False) -> None:
pass
def isinstanceattribute(self) -> bool:
"""Check the subject is an instance attribute."""
warnings.warn('AttributeDocumenter.isinstanceattribute() is deprecated.',
RemovedInSphinx50Warning)
# uninitialized instance variable (PEP-526)
with mock(self.config.autodoc_mock_imports):
try:
ret = import_object(self.modname, self.objpath[:-1], 'class',
attrgetter=self.get_attr,
warningiserror=self.config.autodoc_warningiserror)
self.parent = ret[3]
annotations = get_type_hints(self.parent, None,
self.config.autodoc_type_aliases)
if self.objpath[-1] in annotations:
self.object = UNINITIALIZED_ATTR
return True
except ImportError:
pass
return False
def update_annotations(self, parent: Any) -> None:
"""Update __annotations__ to support type_comment and so on."""
try:
@@ -2694,7 +2649,7 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
return None
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
def get_doc(self) -> Optional[List[List[str]]]:
# Check the attribute has a docstring-comment
comment = self.get_attribute_comment(self.parent, self.objpath[-1])
if comment:
@@ -2706,12 +2661,11 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
# ref: https://github.com/sphinx-doc/sphinx/issues/7805
orig = self.config.autodoc_inherit_docstrings
self.config.autodoc_inherit_docstrings = False # type: ignore
return super().get_doc(ignore)
return super().get_doc()
finally:
self.config.autodoc_inherit_docstrings = orig # type: ignore
def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
) -> None:
def add_content(self, more_content: Optional[StringList]) -> None:
# Disable analyzing attribute comment on Documenter.add_content() to control it on
# AttributeDocumenter.add_content()
self.analyzer = None
@@ -2719,7 +2673,7 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
if more_content is None:
more_content = StringList()
self.update_content(more_content)
super().add_content(more_content, no_docstring)
super().add_content(more_content)
class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): # type: ignore
@@ -2817,12 +2771,6 @@ class NewTypeAttributeDocumenter(AttributeDocumenter):
return not isinstance(parent, ModuleDocumenter) and inspect.isNewType(member)
def get_documenters(app: Sphinx) -> Dict[str, Type[Documenter]]:
"""Returns registered Documenter classes"""
warnings.warn("get_documenters() is deprecated.", RemovedInSphinx50Warning, stacklevel=2)
return app.registry.documenters
def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:
"""Alternative getattr() for types"""
for typ, func in app.registry.autodoc_attrgettrs.items():
@@ -2832,24 +2780,6 @@ def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:
return safe_getattr(obj, name, *defargs)
def migrate_autodoc_member_order(app: Sphinx, config: Config) -> None:
if config.autodoc_member_order == 'alphabetic':
# RemovedInSphinx50Warning
logger.warning(__('autodoc_member_order now accepts "alphabetical" '
'instead of "alphabetic". Please update your setting.'))
config.autodoc_member_order = 'alphabetical' # type: ignore
# for compatibility
from sphinx.ext.autodoc.deprecated import DataDeclarationDocumenter # NOQA
from sphinx.ext.autodoc.deprecated import GenericAliasDocumenter # NOQA
from sphinx.ext.autodoc.deprecated import InstanceAttributeDocumenter # NOQA
from sphinx.ext.autodoc.deprecated import SingledispatchFunctionDocumenter # NOQA
from sphinx.ext.autodoc.deprecated import SingledispatchMethodDocumenter # NOQA
from sphinx.ext.autodoc.deprecated import SlotsAttributeDocumenter # NOQA
from sphinx.ext.autodoc.deprecated import TypeVarDocumenter # NOQA
def setup(app: Sphinx) -> Dict[str, Any]:
app.add_autodocumenter(ModuleDocumenter)
app.add_autodocumenter(ClassDocumenter)
@@ -2865,7 +2795,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
app.add_config_value('autoclass_content', 'class', True, ENUM('both', 'class', 'init'))
app.add_config_value('autodoc_member_order', 'alphabetical', True,
ENUM('alphabetic', 'alphabetical', 'bysource', 'groupwise'))
ENUM('alphabetical', 'bysource', 'groupwise'))
app.add_config_value('autodoc_class_signature', 'mixed', True, ENUM('mixed', 'separated'))
app.add_config_value('autodoc_default_options', {}, True)
app.add_config_value('autodoc_docstring_signature', True, True)
@@ -2873,7 +2803,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
app.add_config_value('autodoc_typehints', "signature", True,
ENUM("signature", "description", "none", "both"))
app.add_config_value('autodoc_typehints_description_target', 'all', True,
ENUM('all', 'documented'))
ENUM('all', 'documented', 'documented_params'))
app.add_config_value('autodoc_type_aliases', {}, True)
app.add_config_value('autodoc_typehints_format', "short", 'env',
ENUM("fully-qualified", "short"))
@@ -2885,8 +2815,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
app.add_event('autodoc-skip-member')
app.add_event('autodoc-process-bases')
app.connect('config-inited', migrate_autodoc_member_order, priority=800)
app.setup_extension('sphinx.ext.autodoc.preserve_defaults')
app.setup_extension('sphinx.ext.autodoc.type_comment')
app.setup_extension('sphinx.ext.autodoc.typehints')

126
sphinx/ext/autodoc/deprecated.py
View File

@@ -1,126 +0,0 @@
"""
sphinx.ext.autodoc.deprecated
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The deprecated Documenters for autodoc.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import warnings
from typing import Any
from sphinx.deprecation import RemovedInSphinx50Warning
from sphinx.ext.autodoc import (AttributeDocumenter, DataDocumenter, FunctionDocumenter,
MethodDocumenter)
class SingledispatchFunctionDocumenter(FunctionDocumenter):
"""
Used to be a specialized Documenter subclass for singledispatch'ed functions.
Retained for backwards compatibility, now does the same as the FunctionDocumenter
"""
def __init__(self, *args: Any, **kwargs: Any) -> None:
warnings.warn("%s is deprecated." % self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
super().__init__(*args, **kwargs)
class DataDeclarationDocumenter(DataDocumenter):
"""
Specialized Documenter subclass for data that cannot be imported
because they are declared without initial value (refs: PEP-526).
"""
objtype = 'datadecl'
directivetype = 'data'
member_order = 60
# must be higher than AttributeDocumenter
priority = 11
def __init__(self, *args: Any, **kwargs: Any) -> None:
warnings.warn("%s is deprecated." % self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
super().__init__(*args, **kwargs)
class TypeVarDocumenter(DataDocumenter):
"""
Specialized Documenter subclass for TypeVars.
"""
objtype = 'typevar'
directivetype = 'data'
priority = DataDocumenter.priority + 1 # type: ignore
def __init__(self, *args: Any, **kwargs: Any) -> None:
warnings.warn("%s is deprecated." % self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
super().__init__(*args, **kwargs)
class SingledispatchMethodDocumenter(MethodDocumenter):
"""
Used to be a specialized Documenter subclass for singledispatch'ed methods.
Retained for backwards compatibility, now does the same as the MethodDocumenter
"""
def __init__(self, *args: Any, **kwargs: Any) -> None:
warnings.warn("%s is deprecated." % self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
super().__init__(*args, **kwargs)
class InstanceAttributeDocumenter(AttributeDocumenter):
"""
Specialized Documenter subclass for attributes that cannot be imported
because they are instance attributes (e.g. assigned in __init__).
"""
objtype = 'instanceattribute'
directivetype = 'attribute'
member_order = 60
# must be higher than AttributeDocumenter
priority = 11
def __init__(self, *args: Any, **kwargs: Any) -> None:
warnings.warn("%s is deprecated." % self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
super().__init__(*args, **kwargs)
class SlotsAttributeDocumenter(AttributeDocumenter):
"""
Specialized Documenter subclass for attributes that cannot be imported
because they are attributes in __slots__.
"""
objtype = 'slotsattribute'
directivetype = 'attribute'
member_order = 60
# must be higher than AttributeDocumenter
priority = 11
def __init__(self, *args: Any, **kwargs: Any) -> None:
warnings.warn("%s is deprecated." % self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
super().__init__(*args, **kwargs)
class GenericAliasDocumenter(DataDocumenter):
"""
Specialized Documenter subclass for GenericAliases.
"""
objtype = 'genericalias'
directivetype = 'data'
priority = DataDocumenter.priority + 1 # type: ignore
def __init__(self, *args: Any, **kwargs: Any) -> None:
warnings.warn("%s is deprecated." % self.__class__.__name__,
RemovedInSphinx50Warning, stacklevel=2)
super().__init__(*args, **kwargs)

16
sphinx/ext/autodoc/directive.py
View File

@@ -1,11 +1,3 @@
"""
sphinx.ext.autodoc.directive
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import warnings
from typing import Any, Callable, Dict, List, Set, Type
@@ -16,7 +8,7 @@ from docutils.statemachine import StringList
from docutils.utils import Reporter, assemble_option_dict
from sphinx.config import Config
from sphinx.deprecation import RemovedInSphinx50Warning, RemovedInSphinx60Warning
from sphinx.deprecation import RemovedInSphinx60Warning
from sphinx.environment import BuildEnvironment
from sphinx.ext.autodoc import Documenter, Options
from sphinx.util import logging
@@ -72,12 +64,6 @@ class DocumenterBridge:
RemovedInSphinx60Warning, stacklevel=2)
return self.record_dependencies
@property
def reporter(self) -> Reporter:
warnings.warn('DocumenterBridge.reporter is deprecated.',
RemovedInSphinx50Warning, stacklevel=2)
return self._reporter
def process_documenter_options(documenter: Type[Documenter], config: Config, options: Dict
) -> Options:

36
sphinx/ext/autodoc/importer.py
View File

@@ -1,19 +1,10 @@
"""
sphinx.ext.autodoc.importer
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Importer utilities for autodoc
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Importer utilities for autodoc"""
import importlib
import traceback
import warnings
from typing import Any, Callable, Dict, List, NamedTuple, Optional, Tuple
from typing import Any, Callable, Dict, List, NamedTuple, Optional
from sphinx.deprecation import RemovedInSphinx50Warning
from sphinx.ext.autodoc.mock import ismock, undecorate
from sphinx.pycode import ModuleAnalyzer, PycodeError
from sphinx.util import logging
@@ -147,29 +138,6 @@ def import_object(modname: str, objpath: List[str], objtype: str = '',
raise ImportError(errmsg) from exc
def get_module_members(module: Any) -> List[Tuple[str, Any]]:
"""Get members of target module."""
from sphinx.ext.autodoc import INSTANCEATTR
warnings.warn('sphinx.ext.autodoc.importer.get_module_members() is deprecated.',
RemovedInSphinx50Warning)
members: Dict[str, Tuple[str, Any]] = {}
for name in dir(module):
try:
value = safe_getattr(module, name, None)
members[name] = (name, value)
except AttributeError:
continue
# annotation only member (ex. attr: int)
for name in getannotations(module):
if name not in members:
members[name] = (name, INSTANCEATTR)
return sorted(list(members.values()))
class Attribute(NamedTuple):
name: str
directly_defined: bool

22
sphinx/ext/autodoc/mock.py
View File

@@ -1,23 +1,15 @@
"""
sphinx.ext.autodoc.mock
~~~~~~~~~~~~~~~~~~~~~~~
mock for autodoc
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""mock for autodoc"""
import contextlib
import os
import sys
from importlib.abc import Loader, MetaPathFinder
from importlib.machinery import ModuleSpec
from types import ModuleType
from types import MethodType, ModuleType
from typing import Any, Generator, Iterator, List, Optional, Sequence, Tuple, Union
from sphinx.util import logging
from sphinx.util.inspect import safe_getattr
from sphinx.util.inspect import isboundmethod, safe_getattr
logger = logging.getLogger(__name__)
@@ -172,9 +164,15 @@ def ismock(subject: Any) -> bool:
if isinstance(subject, _MockModule):
return True
# check the object is bound method
if isinstance(subject, MethodType) and isboundmethod(subject):
tmp_subject = subject.__func__
else:
tmp_subject = subject
try:
# check the object is mocked object
__mro__ = safe_getattr(type(subject), '__mro__', [])
__mro__ = safe_getattr(type(tmp_subject), '__mro__', [])
if len(__mro__) > 2 and __mro__[-2] is _MockObject:
# A mocked object has a MRO that ends with (..., _MockObject, object).
return True

17
sphinx/ext/autodoc/preserve_defaults.py
View File

@@ -1,12 +1,7 @@
"""
sphinx.ext.autodoc.preserve_defaults
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"""Preserve function defaults.
Preserve the default argument values of function signatures in source code
and keep them not evaluated for readability.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
Preserve the default argument values of function signatures in source code
and keep them not evaluated for readability.
"""
import ast
@@ -84,7 +79,11 @@ def update_defvalue(app: Sphinx, obj: Any, bound_method: bool) -> None:
kw_defaults = list(function.args.kw_defaults)
parameters = list(sig.parameters.values())
for i, param in enumerate(parameters):
if param.default is not param.empty:
if param.default is param.empty:
if param.kind == param.KEYWORD_ONLY:
# Consume kw_defaults for kwonly args
kw_defaults.pop(0)
else:
if param.kind in (param.POSITIONAL_ONLY, param.POSITIONAL_OR_KEYWORD):
default = defaults.pop(0)
value = get_default_value(lines, default)

10
sphinx/ext/autodoc/type_comment.py
View File

@@ -1,12 +1,4 @@
"""
sphinx.ext.autodoc.type_comment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Update annotations info of living objects using type_comments.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Update annotations info of living objects using type_comments."""
from inspect import Parameter, Signature, getsource
from typing import Any, Dict, List, cast

Some files were not shown because too many files have changed in this diff Show More