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 '4.x'

Browse Source
This commit is contained in:
Takeshi KOMIYA 2022-03-19 22:58:15 +09:00
commit aa1bc83c2a
419 changed files with 3603 additions and 5735 deletions
Show Stats 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

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

@ -7,6 +7,7 @@ on:
jobs:
push:
if: github.repository_owner == 'sphinx-doc'
runs-on: ubuntu-latest
steps:
@ -27,6 +28,7 @@ jobs:
TX_TOKEN: ${{ secrets.TX_TOKEN }}
pull:
if: github.repository_owner == 'sphinx-doc'
runs-on: ubuntu-latest
steps:

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

4
CHANGES
View File

@ -91,12 +91,16 @@ Deprecated
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
* #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
a Quick search shortcut and :kbd:`Esc` shortcut that
removes search highlighting.
* #10252: C++, support attributes on classes, unions, and enums.
* #10253: :rst:dir:`pep` role now generates URLs based on peps.python.org
Bugs fixed
----------

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.

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

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

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.5",
"resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.5.tgz",
"integrity": "sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw==",
"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"
}

6
setup.cfg
View File

@ -35,12 +35,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

10
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.)

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

10
sphinx/addnodes.py
View File

@ -1,12 +1,4 @@
"""
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

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

10
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

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

10
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

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

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

@ -1,12 +1,4 @@
"""
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

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

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

@ -1,12 +1,4 @@
"""
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
from os import path

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

10
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

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

10
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

10
sphinx/builders/manpage.py
View File

@ -1,12 +1,4 @@
"""
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."""
from os import path
from typing import Any, Dict, List, Set, Tuple, Union

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

10
sphinx/builders/texinfo.py
View File

@ -1,12 +1,4 @@
"""
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
from os import path

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."""

10
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

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

10
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

10
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

10
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

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

8
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

8
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

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

10
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,

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

73
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,
@ -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.
@ -3318,16 +3312,20 @@ 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: List[ASTAttribute]) -> 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 = []
for attr in self.attrs:
res.append(transform(attr) + ' ')
res.append(transform(self.name))
if self.final:
res.append(' final')
@ -3344,6 +3342,9 @@ class ASTClass(ASTBase):
def describe_signature(self, signode: TextElement, mode: str,
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
for attr in self.attrs:
attr.describe_signature(signode)
signode += addnodes.desc_sig_space()
self.name.describe_signature(signode, mode, env, symbol=symbol)
if self.final:
signode += addnodes.desc_sig_space()
@ -3361,8 +3362,9 @@ class ASTClass(ASTBase):
class ASTUnion(ASTBase):
def __init__(self, name: ASTNestedName) -> None:
def __init__(self, name: ASTNestedName, attrs: List[ASTAttribute]) -> None:
self.name = name
self.attrs = attrs
def get_id(self, version: int, objectType: str, symbol: "Symbol") -> str:
if version == 1:
@ -3370,20 +3372,28 @@ class ASTUnion(ASTBase):
return symbol.get_full_nested_name().get_id(version)
def _stringify(self, transform: StringifyTransform) -> str:
return transform(self.name)
res = []
for attr in self.attrs:
res.append(transform(attr) + ' ')
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)
for attr in self.attrs:
attr.describe_signature(signode)
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: List[ASTAttribute]) -> 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 +3405,8 @@ class ASTEnum(ASTBase):
if self.scoped:
res.append(self.scoped)
res.append(' ')
for attr in self.attrs:
res.append(transform(attr) + ' ')
res.append(transform(self.name))
if self.underlyingType:
res.append(' : ')
@ -3405,6 +3417,9 @@ class ASTEnum(ASTBase):
env: "BuildEnvironment", symbol: "Symbol") -> None:
verify_description_mode(mode)
# self.scoped has been done by the CPPEnumObject
for attr in self.attrs:
attr.describe_signature(signode)
signode += addnodes.desc_sig_space()
self.name.describe_signature(signode, mode, env, symbol=symbol)
if self.underlyingType:
signode += addnodes.desc_sig_space()
@ -6567,6 +6582,12 @@ class DefinitionParser(BaseParser):
return ASTConcept(nestedName, initializer)
def _parse_class(self) -> ASTClass:
attrs = []
while 1:
attr = self._parse_attribute()
if attr is None:
break
attrs.append(attr)
name = self._parse_nested_name()
self.skip_ws()
final = self.skip_word_and_ws('final')
@ -6594,21 +6615,33 @@ class DefinitionParser(BaseParser):
continue
else:
break
return ASTClass(name, final, bases)
return ASTClass(name, final, bases, attrs)
def _parse_union(self) -> ASTUnion:
attrs = []
while 1:
attr = self._parse_attribute()
if attr is None:
break
attrs.append(attr)
name = self._parse_nested_name()
return ASTUnion(name)
return ASTUnion(name, attrs)
def _parse_enum(self) -> ASTEnum:
scoped = None # is set by CPPEnumObject
attrs = []
while 1:
attr = self._parse_attribute()
if attr is None:
break
attrs.append(attr)
self.skip_ws()
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()
@ -7992,7 +8025,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
return {
'version': 'builtin',
'env_version': 4,
'env_version': 5,
'parallel_read_safe': True,
'parallel_write_safe': True,
}

10
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

10
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

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

10
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

10
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

10
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

12
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
@ -49,7 +41,7 @@ default_settings: Dict[str, Any] = {
'embed_images': False,
'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,

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."""

19
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

13
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

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

@ -1,12 +1,4 @@
"""
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.
"""
"""The deprecated Documenters for autodoc."""
import warnings
from typing import Any

8
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

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

@ -1,12 +1,4 @@
"""
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

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

@ -1,12 +1,4 @@
"""
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

11
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

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

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

@ -1,12 +1,4 @@
"""
sphinx.ext.autodoc.typehints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Generating content for autodoc using typehints
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Generating content for autodoc using typehints"""
import re
from collections import OrderedDict

10
sphinx/ext/autosectionlabel.py
View File

@ -1,12 +1,4 @@
"""
sphinx.ext.autosectionlabel
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Allow reference sections by :ref: role using its title.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Allow reference sections by :ref: role using its title."""
from typing import Any, Dict, cast

70
sphinx/ext/autosummary/__init__.py
View File

@ -1,55 +1,49 @@
"""
sphinx.ext.autosummary
~~~~~~~~~~~~~~~~~~~~~~
"""Extension that adds an autosummary:: directive.
Sphinx extension that adds an autosummary:: directive, which can be
used to generate function/method/attribute/etc. summary lists, similar
to those output eg. by Epydoc and other API doc generation tools.
The directive can be used to generate function/method/attribute/etc. summary
lists, similar to those output eg. by Epydoc and other API doc generation tools.
An :autolink: role is also provided.
An :autolink: role is also provided.
autosummary directive
---------------------
autosummary directive
---------------------
The autosummary directive has the form::
The autosummary directive has the form::
.. autosummary::
:nosignatures:
:toctree: generated/
.. autosummary::
:nosignatures:
:toctree: generated/
module.function_1
module.function_2
...
module.function_1
module.function_2
...
and it generates an output table (containing signatures, optionally)
and it generates an output table (containing signatures, optionally)
======================== =============================================
module.function_1(args) Summary line from the docstring of function_1
module.function_2(args) Summary line from the docstring
...
======================== =============================================
======================== =============================================
module.function_1(args) Summary line from the docstring of function_1
module.function_2(args) Summary line from the docstring
...
======================== =============================================
If the :toctree: option is specified, files matching the function names
are inserted to the toctree with the given prefix:
If the :toctree: option is specified, files matching the function names
are inserted to the toctree with the given prefix:
generated/module.function_1
generated/module.function_2
...
generated/module.function_1
generated/module.function_2
...
Note: The file names contain the module:: or currentmodule:: prefixes.
Note: The file names contain the module:: or currentmodule:: prefixes.
.. seealso:: autosummary_generate.py
.. seealso:: autosummary_generate.py
autolink role
-------------
autolink role
-------------
The autolink role functions as ``:obj:`` when the name referred can be
resolved to a Python object, and otherwise it becomes simple emphasis.
This can be used as the default role to make links 'smart'.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
The autolink role functions as ``:obj:`` when the name referred can be
resolved to a Python object, and otherwise it becomes simple emphasis.
This can be used as the default role to make links 'smart'.
"""
import inspect
@ -417,7 +411,7 @@ class Autosummary(SphinxDirective):
table_spec['spec'] = r'\X{1}{2}\X{1}{2}'
table = autosummary_table('')
real_table = nodes.table('', classes=['longtable'])
real_table = nodes.table('', classes=['autosummary longtable'])
table.append(real_table)
group = nodes.tgroup('', cols=2)
real_table.append(group)

21
sphinx/ext/autosummary/generate.py
View File

@ -1,20 +1,15 @@
"""
sphinx.ext.autosummary.generate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"""Generates reST source files for autosummary.
Usable as a library or script to generate automatic RST source files for
items referred to in autosummary:: directives.
Usable as a library or script to generate automatic RST source files for
items referred to in autosummary:: directives.
Each generated RST file contains a single auto*:: directive which
extracts the docstring of the referred item.
Each generated RST file contains a single auto*:: directive which
extracts the docstring of the referred item.
Example Makefile rule::
Example Makefile rule::
generate:
sphinx-autogen -o source/generated source/*.rst
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
generate:
sphinx-autogen -o source/generated source/*.rst
"""
import argparse

11
sphinx/ext/coverage.py
View File

@ -1,12 +1,7 @@
"""
sphinx.ext.coverage
~~~~~~~~~~~~~~~~~~~
"""Check Python modules and C API for coverage.
Check Python modules and C API for coverage. Mostly written by Josip
Dzolonga for the Google Highly Open Participation contest.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
Mostly written by Josip Dzolonga for the Google Highly Open Participation
contest.
"""
import glob

10
sphinx/ext/doctest.py
View File

@ -1,12 +1,6 @@
"""
sphinx.ext.doctest
~~~~~~~~~~~~~~~~~~
"""Mimic doctest in Sphinx.
Mimic doctest by automatically executing code snippets and checking
their results.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
The extension automatically execute code snippets and checks their results.
"""
import doctest

10
sphinx/ext/duration.py
View File

@ -1,12 +1,4 @@
"""
sphinx.ext.duration
~~~~~~~~~~~~~~~~~~~
Measure durations of Sphinx processing.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Measure durations of Sphinx processing."""
from datetime import datetime, timedelta
from itertools import islice

30
sphinx/ext/extlinks.py
View File

@ -1,28 +1,20 @@
"""
sphinx.ext.extlinks
~~~~~~~~~~~~~~~~~~~
"""Extension to save typing and prevent hard-coding of base URLs in reST files.
Extension to save typing and prevent hard-coding of base URLs in the reST
files.
This adds a new config value called ``extlinks`` that is created like this::
This adds a new config value called ``extlinks`` that is created like this::
extlinks = {'exmpl': ('https://example.invalid/%s.html', caption), ...}
extlinks = {'exmpl': ('https://example.invalid/%s.html', caption), ...}
Now you can use e.g. :exmpl:`foo` in your documents. This will create a
link to ``https://example.invalid/foo.html``. The link caption depends on
the *caption* value given:
Now you can use e.g. :exmpl:`foo` in your documents. This will create a
link to ``https://example.invalid/foo.html``. The link caption depends on
the *caption* value given:
- If it is ``None``, the caption will be the full URL.
- If it is a string, it must contain ``%s`` exactly once. In this case the
caption will be *caption* with the role content substituted for ``%s``.
- If it is ``None``, the caption will be the full URL.
- If it is a string, it must contain ``%s`` exactly once. In this case the
caption will be *caption* with the role content substituted for ``%s``.
You can also give an explicit caption, e.g. :exmpl:`Foo <foo>`.
You can also give an explicit caption, e.g. :exmpl:`Foo <foo>`.
Both, the url string and the caption string must escape ``%`` as ``%%``.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
Both, the url string and the caption string must escape ``%`` as ``%%``.
"""
import re

10
sphinx/ext/githubpages.py
View File

@ -1,12 +1,4 @@
"""
sphinx.ext.githubpages
~~~~~~~~~~~~~~~~~~~~~~
To publish HTML docs at GitHub Pages, create .nojekyll file.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""To publish HTML docs at GitHub Pages, create .nojekyll file."""
import os
import urllib

10
sphinx/ext/graphviz.py
View File

@ -1,12 +1,4 @@
"""
sphinx.ext.graphviz
~~~~~~~~~~~~~~~~~~~
Allow graphviz-formatted graphs to be included in Sphinx-generated
documents inline.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""Allow graphviz-formatted graphs to be included inline in generated documents.
"""
import posixpath

23
sphinx/ext/ifconfig.py
View File

@ -1,22 +1,17 @@
"""
sphinx.ext.ifconfig
~~~~~~~~~~~~~~~~~~~
"""Provides the ``ifconfig`` directive.
Provides the ``ifconfig`` directive that allows to write documentation
that is included depending on configuration variables.
The ``ifconfig`` directive enables writing documentation
that is included depending on configuration variables.
Usage::
Usage::
.. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
.. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
This stuff is only included in the built docs for unstable versions.
This stuff is only included in the built docs for unstable versions.
The argument for ``ifconfig`` is a plain Python expression, evaluated in the
namespace of the project configuration (that is, all variables from
``conf.py`` are available.)
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
The argument for ``ifconfig`` is a plain Python expression, evaluated in the
namespace of the project configuration (that is, all variables from
``conf.py`` are available.)
"""
from typing import Any, Dict, List

10
sphinx/ext/imgconverter.py
View File

@ -1,12 +1,4 @@
"""
sphinx.ext.imgconverter
~~~~~~~~~~~~~~~~~~~~~~~
Image converter extension for Sphinx
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Image converter extension for Sphinx"""
import subprocess
import sys

10
sphinx/ext/imgmath.py
View File

@ -1,12 +1,4 @@
"""
sphinx.ext.imgmath
~~~~~~~~~~~~~~~~~~
Render math in HTML via dvipng or dvisvgm.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Render math in HTML via dvipng or dvisvgm."""
import posixpath
import re

47
sphinx/ext/inheritance_diagram.py
View File

@ -1,38 +1,31 @@
r"""
sphinx.ext.inheritance_diagram
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
r"""Defines a docutils directive for inserting inheritance diagrams.
Defines a docutils directive for inserting inheritance diagrams.
Provide the directive with one or more classes or modules (separated
by whitespace). For modules, all of the classes in that module will
be used.
Provide the directive with one or more classes or modules (separated
by whitespace). For modules, all of the classes in that module will
be used.
Example::
Example::
Given the following classes:
Given the following classes:
class A: pass
class B(A): pass
class C(A): pass
class D(B, C): pass
class E(B): pass
class A: pass
class B(A): pass
class C(A): pass
class D(B, C): pass
class E(B): pass
.. inheritance-diagram: D E
.. inheritance-diagram: D E
Produces a graph like the following:
Produces a graph like the following:
A
/ \
B C
/ \ /
E D
A
/ \
B C
/ \ /
E D
The graph is inserted as a PNG+image map into HTML and a PDF in
LaTeX.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
The graph is inserted as a PNG+image map into HTML and a PDF in
LaTeX.
"""
import builtins

31
sphinx/ext/intersphinx.py
View File

@ -1,26 +1,19 @@
"""
sphinx.ext.intersphinx
~~~~~~~~~~~~~~~~~~~~~~
"""Insert links to objects documented in remote Sphinx documentation.
Insert links to objects documented in remote Sphinx documentation.
This works as follows:
This works as follows:
* Each Sphinx HTML build creates a file named "objects.inv" that contains a
mapping from object names to URIs relative to the HTML set's root.
* Each Sphinx HTML build creates a file named "objects.inv" that contains a
mapping from object names to URIs relative to the HTML set's root.
* Projects using the Intersphinx extension can specify links to such mapping
files in the `intersphinx_mapping` config value. The mapping will then be
used to resolve otherwise missing references to objects into links to the
other documentation.
* Projects using the Intersphinx extension can specify links to such mapping
files in the `intersphinx_mapping` config value. The mapping will then be
used to resolve otherwise missing references to objects into links to the
other documentation.
* By default, the mapping file is assumed to be at the same location as the
rest of the documentation; however, the location of the mapping file can
also be specified individually, e.g. if the docs should be buildable
without Internet access.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
* By default, the mapping file is assumed to be at the same location as the
rest of the documentation; however, the location of the mapping file can
also be specified individually, e.g. if the docs should be buildable
without Internet access.
"""
import concurrent.futures

10
sphinx/ext/linkcode.py
View File

@ -1,12 +1,4 @@
"""
sphinx.ext.linkcode
~~~~~~~~~~~~~~~~~~~
Add external links to module code in Python object descriptions.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Add external links to module code in Python object descriptions."""
from typing import Any, Dict, Set

11
sphinx/ext/mathjax.py
View File

@ -1,13 +1,8 @@
"""
sphinx.ext.mathjax
~~~~~~~~~~~~~~~~~~
"""Allow `MathJax`_ to be used to display math in Sphinx's HTML writer.
Allow `MathJax <https://www.mathjax.org/>`_ to be used to display math in
Sphinx's HTML writer -- requires the MathJax JavaScript library on your
webserver/computer.
This requires the MathJax JavaScript library on your webserver/computer.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
.. _MathJax: https://www.mathjax.org/
"""
import json

10
sphinx/ext/napoleon/__init__.py
View File

@ -1,12 +1,4 @@
"""
sphinx.ext.napoleon
~~~~~~~~~~~~~~~~~~~
Support for NumPy and Google style docstrings.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Support for NumPy and Google style docstrings."""
from typing import Any, Dict, List

12
sphinx/ext/napoleon/docstring.py
View File

@ -1,14 +1,4 @@
"""
sphinx.ext.napoleon.docstring
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Classes for docstring parsing and formatting.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""Classes for docstring parsing and formatting."""
import collections
import inspect

12
sphinx/ext/napoleon/iterators.py
View File

@ -1,14 +1,4 @@
"""
sphinx.ext.napoleon.iterators
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A collection of helpful iterators.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
"""A collection of helpful iterators."""
import collections
from typing import Any, Iterable, Optional

14
sphinx/ext/todo.py
View File

@ -1,14 +1,8 @@
"""
sphinx.ext.todo
~~~~~~~~~~~~~~~
"""Allow todos to be inserted into your documentation.
Allow todos to be inserted into your documentation. Inclusion of todos can
be switched of by a configuration variable. The todolist directive collects
all todos of your project and lists them along with a backlink to the
original location.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
Inclusion of todos can be switched of by a configuration variable.
The todolist directive collects all todos of your project and lists them along
with a backlink to the original location.
"""
from typing import Any, Dict, List, Tuple, cast

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