mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge branch '3.x' into 8183
This commit is contained in:
Takeshi KOMIYA
commit
87121c3de0
5
.github/ISSUE_TEMPLATE/config.yml
vendored
5
.github/ISSUE_TEMPLATE/config.yml
vendored
@ -2,5 +2,8 @@
|
||||
blank_issues_enabled: false # default: true
|
||||
contact_links:
|
||||
- name: Question
|
||||
url: https://stackoverflow.com/questions/tagged/python-sphinx
|
||||
about: For Q&A purpose, please use Stackoverflow with the tag python-sphinx
|
||||
- name: Discussion
|
||||
url: https://groups.google.com/forum/#!forum/sphinx-users
|
||||
about: For Q&A purpose, please use sphinx-users mailing list.
|
||||
about: For general discussion, please use sphinx-users mailing list.
|
||||
|
||||
@ -24,9 +24,6 @@ jobs:
|
||||
env:
|
||||
- TOXENV=du15
|
||||
- PYTEST_ADDOPTS="--cov ./ --cov-append --cov-config setup.cfg"
|
||||
- python: 'nightly'
|
||||
env:
|
||||
- TOXENV=du16
|
||||
|
||||
- language: node_js
|
||||
node_js: '10.7'
|
||||
|
||||
92
CHANGES
92
CHANGES
@ -1,3 +1,86 @@
|
||||
Release 3.3.0 (in development)
|
||||
==============================
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
Incompatible changes
|
||||
--------------------
|
||||
|
||||
Deprecated
|
||||
----------
|
||||
|
||||
* ``sphinx.builders.latex.LaTeXBuilder.usepackages``
|
||||
* ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref``
|
||||
* ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter``
|
||||
* ``sphinx.ext.autodoc.SingledispatchMethodDocumenter``
|
||||
|
||||
Features added
|
||||
--------------
|
||||
|
||||
* #8100: html: Show a better error message for failures on copying
|
||||
html_static_files
|
||||
* #8141: C: added a ``maxdepth`` option to :rst:dir:`c:alias` to insert
|
||||
nested declarations.
|
||||
* #8081: LaTeX: Allow to add LaTeX package via ``app.add_latex_package()`` until
|
||||
just before writing .tex file
|
||||
* #7996: manpage: Add :confval:`man_make_section_directory` to make a section
|
||||
directory on build man page
|
||||
* #8289: epub: Allow to suppress "duplicated ToC entry found" warnings from epub
|
||||
builder using :confval:`suppress_warnings`.
|
||||
* #8298: sphinx-quickstart: Add :option:`sphinx-quickstart --no-sep` option
|
||||
* #8304: sphinx.testing: Register public markers in sphinx.testing.fixtures
|
||||
* #8051: napoleon: use the obj role for all See Also items
|
||||
* #8050: napoleon: Apply :confval:`napoleon_preprocess_types` to every field
|
||||
|
||||
Bugs fixed
|
||||
----------
|
||||
|
||||
* #8085: i18n: Add support for having single text domain
|
||||
* #6640: i18n: Failed to override system message translation
|
||||
* #8143: autodoc: AttributeError is raised when False value is passed to
|
||||
autodoc_default_options
|
||||
* #8103: autodoc: functools.cached_property is not considered as a property
|
||||
* #8190: autodoc: parsing error is raised if some extension replaces docstring
|
||||
by string not ending with blank lines
|
||||
* #8142: autodoc: Wrong constructor signature for the class derived from
|
||||
typing.Generic
|
||||
* #8157: autodoc: TypeError is raised when annotation has invalid __args__
|
||||
* #7964: autodoc: Tuple in default value is wrongly rendered
|
||||
* #8200: autodoc: type aliases break type formatting of autoattribute
|
||||
* #7786: autodoc: can't detect overloaded methods defined in other file
|
||||
* #8294: autodoc: single-string __slots__ is not handled correctly
|
||||
* #7785: autodoc: autodoc_typehints='none' does not effect to overloaded functions
|
||||
* #8192: napoleon: description is disappeared when it contains inline literals
|
||||
* #8142: napoleon: Potential of regex denial of service in google style docs
|
||||
* #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex
|
||||
* #8215: LaTeX: 'oneside' classoption causes build warning
|
||||
* #8175: intersphinx: Potential of regex denial of service by broken inventory
|
||||
* #8277: sphinx-build: missing and redundant spacing (and etc) for console
|
||||
output on building
|
||||
* #7973: imgconverter: Check availability of imagemagick many times
|
||||
* #8255: py domain: number in default argument value is changed from hexadecimal
|
||||
to decimal
|
||||
* #8316: html: Prevent arrow keys changing page when button elements are focused
|
||||
* #8343: html search: Fix unnecessary load of images when parsing the document
|
||||
* #8254: html theme: Line numbers misalign with code lines
|
||||
* #8093: The highlight warning has wrong location in some builders (LaTeX,
|
||||
singlehtml and so on)
|
||||
* #8215: Eliminate Fancyhdr build warnings for oneside documents
|
||||
* #8239: Failed to refer a token in productionlist if it is indented
|
||||
* #8268: linkcheck: Report HTTP errors when ``linkcheck_anchors`` is ``True``
|
||||
* #8245: linkcheck: take source directory into account for local files
|
||||
* #8321: linkcheck: ``tel:`` schema hyperlinks are detected as errors
|
||||
* #8323: linkcheck: An exit status is incorrect when links having unsupported
|
||||
schema found
|
||||
* #6914: figure numbers are unexpectedly assigned to uncaptioned items
|
||||
* #8320: make "inline" line numbers un-selectable
|
||||
|
||||
Testing
|
||||
--------
|
||||
|
||||
* #8257: Support parallel build in sphinx.testing
|
||||
|
||||
Release 3.2.2 (in development)
|
||||
==============================
|
||||
|
||||
@ -16,6 +99,15 @@ Features added
|
||||
Bugs fixed
|
||||
----------
|
||||
|
||||
* #8188: C, add missing items to internal object types dictionary,
|
||||
e.g., preventing intersphinx from resolving them.
|
||||
* C, fix anon objects in intersphinx.
|
||||
* #8270, C++, properly reject functions as duplicate declarations if a
|
||||
non-function declaration of the same name already exists.
|
||||
* C, fix references to function parameters.
|
||||
Link to the function instead of a non-existing anchor.
|
||||
|
||||
|
||||
Testing
|
||||
--------
|
||||
|
||||
|
||||
2
EXAMPLES
2
EXAMPLES
@ -230,6 +230,7 @@ Documentation using sphinx_rtd_theme
|
||||
* `MyHDL <http://docs.myhdl.org/>`__
|
||||
* `Nextflow <https://www.nextflow.io/docs/latest/index.html>`__
|
||||
* `NICOS <https://forge.frm2.tum.de/nicos/doc/nicos-master/>`__ (customized)
|
||||
* `OpenFAST <https://openfast.readthedocs.io/>`__
|
||||
* `Pelican <http://docs.getpelican.com/>`__
|
||||
* `picamera <https://picamera.readthedocs.io/>`__
|
||||
* `Pillow <https://pillow.readthedocs.io/>`__
|
||||
@ -330,6 +331,7 @@ Documentation using a custom theme or integrated in a website
|
||||
* `Lasso <http://lassoguide.com/>`__
|
||||
* `Mako <http://docs.makotemplates.org/>`__
|
||||
* `MirrorBrain <http://mirrorbrain.org/docs/>`__
|
||||
* `Mitiq <https://mitiq.readthedocs.io/>`__
|
||||
* `MongoDB <https://docs.mongodb.com/>`__
|
||||
* `Music21 <https://web.mit.edu/music21/doc/>`__
|
||||
* `MyHDL <http://docs.myhdl.org/>`__
|
||||
|
||||
4
Makefile
4
Makefile
@ -64,10 +64,6 @@ type-check:
|
||||
doclinter:
|
||||
python utils/doclinter.py CHANGES *.rst doc/
|
||||
|
||||
.PHONY: pylint
|
||||
pylint:
|
||||
@pylint --rcfile utils/pylintrc sphinx
|
||||
|
||||
.PHONY: test
|
||||
test:
|
||||
@$(PYTHON) -m pytest -v $(TEST)
|
||||
|
||||
8
doc/_static/favicon.svg
vendored
Normal file
8
doc/_static/favicon.svg
vendored
Normal file
@ -0,0 +1,8 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
|
||||
<style>
|
||||
@media (prefers-color-scheme: dark) {
|
||||
svg { fill: white; }
|
||||
}
|
||||
</style>
|
||||
<path d="m 67.780707,71.526216 c 0,-2.720856 0.735772,-7.633735 1.635035,-10.917507 2.076574,-7.582764 3.222746,-16.97568 2.071477,-16.97568 -0.485619,0 -3.994408,3.173002 -7.797313,7.051115 -14.448869,14.734603 -29.952812,23.068339 -42.915946,23.068339 -7.400211,0 -12.4298817,-1.871115 -17.2867007,-6.430912 -2.94436186,-2.764297 -3.47532146,-4.129685 -3.47532146,-8.936928 0,-4.94488 0.4862322,-6.108589 3.78321146,-9.054437 2.987989,-2.669773 4.875111,-3.380296 8.9779137,-3.380296 3.163221,0.711278 5.032659,0.664017 6.063532,1.917191 1.045041,1.231842 1.406892,5.262673 0.143323,7.623675 -0.674746,1.260763 -2.435471,2.043539 -4.5966,2.043539 -2.040303,0 -3.203991,-0.483702 -2.786976,-1.15844 1.31395,-2.126021 -0.560952,-3.566616 -2.9664067,-2.279256 -2.907025,1.555792 -2.957418,7.069066 -0.08839,9.665535 4.0345357,3.651203 15.1912207,5.023925 21.9019857,2.694828 7.250749,-2.516503 16.739014,-8.578986 24.30831,-15.531674 l 6.657407,-6.115083 -8.688303,-0.05007 C 43.622519,44.707714 37.702703,43.621524 18.54695,38.489741 12.175528,36.782852 6.0502733,35.306342 4.9352743,35.208608 3.6710803,35.097791 2.841723,34.067882 2.9080043,32.476074 3.0199286,29.788108 4.4800823,27.78768 6.2067673,27.033038 7.2437505,26.579828 14.43583,25.894406 22.0605,23.866486 c 29.699148,-7.899023 31.502043,-6.781254 51.28707,-1.772167 6.461504,1.635896 13.942408,3.414988 17.256961,3.474566 5.106245,0.09178 6.211825,0.514653 7.240255,2.76932 0.66758,1.46355 1.21378,2.858905 1.21378,3.10079 0,0.241884 -2.89333,1.764397 -6.429613,3.383363 -12.984983,5.944723 -17.083271,9.093943 -12.855172,15.130399 1.753219,2.503069 1.718037,2.768923 -0.57922,4.37799 -1.345193,0.942203 -2.457238,2.856456 -2.471232,4.253898 -0.03777,3.776976 -2.424786,11.884847 -5.893734,15.080164 l -3.048923,2.808424 z m 6.632814,-34.658372 c 5.169656,-1.440693 8.302047,-3.07045 14.72913,-6.500861 -5.292267,-1.548658 -18.570782,-3.724097 -18.570782,-3.724097 -9.796513,-1.964547 -8.76916,-1.865132 -9.21348,0.29669 -0.176673,0.859598 -0.702644,2.763948 -1.872329,4.596663 -2.251474,3.527711 -10.489307,4.271075 -15.214327,2.009703 -1.482367,-0.709454 -2.971272,-3.416276 -2.950606,-5.336922 0.02911,-2.705486 -1.505386,-3.336055 -2.486689,-2.975309 -0.796428,0.292781 -3.384665,0.330004 -9.071284,1.864262 -18.784765,5.068157 -21.3552119,4.487473 -9.110967,6.223299 1.472409,0.208739 9.252992,2.381926 13.052028,3.39412 9.318588,2.482796 11.064717,2.665087 23.125496,2.414247 8.385835,-0.174409 11.891174,-0.675356 17.58381,-2.261795 z M 3.0589449,14.916483 C 3.2921927,12.514245 3.424378,11.992797 10.100599,10.647894 13.924923,9.8774962 23.355266,7.3808108 31.056903,5.0997052 c 17.703937,-5.2436279 22.73392,-5.2565016 41.092202,-0.105175 7.923233,2.2232606 16.798382,4.047803 19.72254,4.054541 4.567242,0.01054 6.941892,2.0284768 6.941892,2.0284768 2.101843,4.825342 1.718463,5.158474 -6.484103,5.158474 -5.714193,0 -10.641875,-0.963081 -18.245438,-3.565943 C 68.300078,10.69012 60.060462,8.8316882 55.557963,8.4915615 47.342337,7.8709375 47.353713,7.8687835 21.963188,14.855617 17.503192,16.082896 11.34213,17.454164 8.2719268,17.902883 l -5.5821654,0.81585 z" />
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 3.2 KiB |
@ -28,6 +28,7 @@ html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
|
||||
html_additional_pages = {'index': 'index.html'}
|
||||
html_use_opensearch = 'https://www.sphinx-doc.org/en/master'
|
||||
html_baseurl = 'https://www.sphinx-doc.org/en/master/'
|
||||
html_favicon = '_static/favicon.svg'
|
||||
|
||||
htmlhelp_basename = 'Sphinxdoc'
|
||||
|
||||
@ -110,8 +111,6 @@ texinfo_documents = [
|
||||
1),
|
||||
]
|
||||
|
||||
# We're not using intersphinx right now, but if we did, this would be part of
|
||||
# the mapping:
|
||||
intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}
|
||||
|
||||
# Sphinx document translation with sphinx gettext feature uses these settings:
|
||||
|
||||
@ -140,14 +140,14 @@ started with writing your own extensions.
|
||||
.. _slideshare: https://www.slideshare.net/
|
||||
.. _TikZ/PGF LaTeX package: https://sourceforge.net/projects/pgf/
|
||||
.. _MATLAB: https://www.mathworks.com/products/matlab.html
|
||||
.. _swf: https://bitbucket.org/klorenz/sphinxcontrib-swf
|
||||
.. _findanything: https://bitbucket.org/klorenz/sphinxcontrib-findanything
|
||||
.. _cmakedomain: https://bitbucket.org/klorenz/sphinxcontrib-cmakedomain
|
||||
.. _swf: https://github.com/sphinx-contrib/swf
|
||||
.. _findanything: https://github.com/sphinx-contrib/findanything
|
||||
.. _cmakedomain: https://github.com/sphinx-contrib/cmakedomain
|
||||
.. _GNU Make: https://www.gnu.org/software/make/
|
||||
.. _makedomain: https://bitbucket.org/klorenz/sphinxcontrib-makedomain
|
||||
.. _makedomain: https://github.com/sphinx-contrib/makedomain
|
||||
.. _inlinesyntaxhighlight: https://sphinxcontrib-inlinesyntaxhighlight.readthedocs.io/
|
||||
.. _CMake: https://cmake.org
|
||||
.. _domaintools: https://bitbucket.org/klorenz/sphinxcontrib-domaintools
|
||||
.. _domaintools: https://github.com/sphinx-contrib/domaintools
|
||||
.. _restbuilder: https://pypi.org/project/sphinxcontrib-restbuilder/
|
||||
.. _Lasso: http://www.lassosoft.com/
|
||||
.. _beamer: https://pypi.org/project/sphinxcontrib-beamer/
|
||||
|
||||
@ -177,17 +177,18 @@ type for that event::
|
||||
9. (if running in parallel mode, for each process) event.env-merged-info(app, env, docnames, other)
|
||||
10. event.env-updated(app, env)
|
||||
11. event.env-get-updated(app, env)
|
||||
11. event.env-check-consistency(app, env)
|
||||
12. event.env-check-consistency(app, env)
|
||||
|
||||
# The updated-docs list can be builder dependent, but generally includes all new/changed documents,
|
||||
# plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
|
||||
# For builders that output a single page, they are first joined into a single doctree before post-transforms/doctree-resolved
|
||||
for docname in docnames:
|
||||
12. apply post-transforms (by priority): docutils.document -> docutils.document
|
||||
13. event.doctree-resolved(app, doctree, docname)
|
||||
for docname in updated-docs:
|
||||
13. apply post-transforms (by priority): docutils.document -> docutils.document
|
||||
14. event.doctree-resolved(app, doctree, docname)
|
||||
- (for any reference node that fails to resolve) event.missing-reference(env, node, contnode)
|
||||
|
||||
14. Generate output files
|
||||
|
||||
15. event.build-finished(app, exception)
|
||||
15. Generate output files
|
||||
16. event.build-finished(app, exception)
|
||||
|
||||
Here is a more detailed list of these events.
|
||||
|
||||
|
||||
@ -26,6 +26,26 @@ The following is a list of deprecated interfaces.
|
||||
- (will be) Removed
|
||||
- Alternatives
|
||||
|
||||
* - ``sphinx.builders.latex.LaTeXBuilder.usepackages``
|
||||
- 3.3
|
||||
- 5.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref``
|
||||
- 3.3
|
||||
- 5.0
|
||||
- N/A
|
||||
|
||||
* - ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter``
|
||||
- 3.3
|
||||
- 5.0
|
||||
- ``sphinx.ext.autodoc.FunctionDocumenter``
|
||||
|
||||
* - ``sphinx.ext.autodoc.SingledispatchMethodDocumenter``
|
||||
- 3.3
|
||||
- 5.0
|
||||
- ``sphinx.ext.autodoc.MethodDocumenter``
|
||||
|
||||
* - ``sphinx.ext.autodoc.members_set_option()``
|
||||
- 3.2
|
||||
- 5.0
|
||||
|
||||
@ -9,8 +9,8 @@ Glossary
|
||||
A class (inheriting from :class:`~sphinx.builders.Builder`) that takes
|
||||
parsed documents and performs an action on them. Normally, builders
|
||||
translate the documents to an output format, but it is also possible to
|
||||
use the builder builders that e.g. check for broken links in the
|
||||
documentation, or build coverage information.
|
||||
use builders that e.g. check for broken links in the documentation, or
|
||||
build coverage information.
|
||||
|
||||
See :doc:`/usage/builders/index` for an overview over Sphinx's built-in
|
||||
builders.
|
||||
|
||||
@ -12,6 +12,9 @@ Getting help
|
||||
|
||||
The Sphinx community maintains a number of mailing lists and IRC channels.
|
||||
|
||||
Stack Overflow with tag `python-sphinx`_
|
||||
Questions and answers about use and development.
|
||||
|
||||
sphinx-users <sphinx-users@googlegroups.com>
|
||||
Mailing list for user support.
|
||||
|
||||
@ -21,6 +24,7 @@ sphinx-dev <sphinx-dev@googlegroups.com>
|
||||
#sphinx-doc on irc.freenode.net
|
||||
IRC channel for development questions and user support.
|
||||
|
||||
.. _python-sphinx: https://stackoverflow.com/questions/tagged/python-sphinx
|
||||
|
||||
Bug Reports and Feature Requests
|
||||
--------------------------------
|
||||
|
||||
@ -33,6 +33,10 @@ Options
|
||||
|
||||
If specified, separate source and build directories.
|
||||
|
||||
.. option:: --no-sep
|
||||
|
||||
If specified, create build directroy under source directroy.
|
||||
|
||||
.. option:: --dot=DOT
|
||||
|
||||
Inside the root directory, two more directories will be created;
|
||||
|
||||
@ -316,6 +316,7 @@ General configuration
|
||||
* ``toc.circular``
|
||||
* ``toc.secnum``
|
||||
* ``epub.unknown_project_files``
|
||||
* ``epub.duplicated_toc_entry``
|
||||
* ``autosectionlabel.*``
|
||||
|
||||
You can choose from these types.
|
||||
@ -340,6 +341,10 @@ General configuration
|
||||
|
||||
Added ``autosectionlabel.*``
|
||||
|
||||
.. versionchanged:: 3.3.0
|
||||
|
||||
Added ``epub.duplicated_toc_entry``
|
||||
|
||||
.. confval:: needs_sphinx
|
||||
|
||||
If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
|
||||
@ -756,9 +761,15 @@ documentation on :ref:`intl` for details.
|
||||
If true, a document's text domain is its docname if it is a top-level
|
||||
project file and its very base directory otherwise.
|
||||
|
||||
If set to string, all document's text domain is this string, making all
|
||||
documents use single text domain.
|
||||
|
||||
By default, the document ``markup/code.rst`` ends up in the ``markup`` text
|
||||
domain. With this option set to ``False``, it is ``markup/code``.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
The string value is now accepted.
|
||||
|
||||
.. confval:: gettext_uuid
|
||||
|
||||
If true, Sphinx generates uuid information for version tracking in message
|
||||
@ -2239,6 +2250,12 @@ These options influence manual page output.
|
||||
|
||||
.. versionadded:: 1.1
|
||||
|
||||
.. confval:: man_make_section_directory
|
||||
|
||||
If true, make a section directory on build man page. Default is False.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. _texinfo-options:
|
||||
|
||||
|
||||
@ -229,7 +229,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
|
||||
|
||||
.. versionchanged:: 3.0
|
||||
|
||||
It takes an anchestor class name as an argument.
|
||||
It takes an ancestor class name as an argument.
|
||||
|
||||
* It's possible to override the signature for explicitly documented callable
|
||||
objects (functions, methods, classes) with the regular syntax that will
|
||||
@ -515,6 +515,44 @@ There are also config values that you can set:
|
||||
|
||||
New option ``'description'`` 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
|
||||
annotations``.
|
||||
|
||||
For example, there is code using a type alias::
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
|
||||
|
||||
def f() -> AliasType:
|
||||
...
|
||||
|
||||
If ``autodoc_type_aliases`` is not set, autodoc will generate internal mark-up
|
||||
from this code as following::
|
||||
|
||||
.. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
|
||||
|
||||
...
|
||||
|
||||
If you set ``autodoc_type_aliases`` as
|
||||
``{'AliasType': 'your.module.TypeAlias'}``, it generates a following document
|
||||
internally::
|
||||
|
||||
.. py:function:: f() -> your.module.AliasType:
|
||||
|
||||
...
|
||||
|
||||
.. __: https://www.python.org/dev/peps/pep-0563/
|
||||
.. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. confval:: autodoc_warningiserror
|
||||
|
||||
This value controls the behavior of :option:`sphinx-build -W` during
|
||||
|
||||
@ -15,7 +15,7 @@ Much of Sphinx's power comes from the richness of its default plain-text markup
|
||||
format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with
|
||||
it's :doc:`significant extensibility capabilities </development/index>`.
|
||||
|
||||
The goal of this document is to give you a quick taste of what Sphinx it is and
|
||||
The goal of this document is to give you a quick taste of what Sphinx is and
|
||||
how you might use it. When you're done here, you can check out the
|
||||
:doc:`installation guide </usage/installation>` followed by the intro to the
|
||||
default markup format used by Sphinx, :doc:`reStucturedText
|
||||
|
||||
@ -744,6 +744,18 @@ The following directive can be used for this purpose.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. rubric:: Options
|
||||
|
||||
.. rst:directive:option:: maxdepth: int
|
||||
|
||||
Insert nested declarations as well, up to the total depth given.
|
||||
Use 0 for infinite depth and 1 for just the mentioned declaration.
|
||||
Defaults to 1.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:namespace-pop::
|
||||
|
||||
|
||||
|
||||
22
package-lock.json
generated
22
package-lock.json
generated
@ -385,12 +385,6 @@
|
||||
"integrity": "sha1-Aljq5NPQwJdN4cFpGI7wBR0dGYg=",
|
||||
"dev": true
|
||||
},
|
||||
"eventemitter3": {
|
||||
"version": "3.1.2",
|
||||
"resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-3.1.2.tgz",
|
||||
"integrity": "sha512-tvtQIeLVHjDkJYnzf2dgVMxfuSGJeM/7UCG17TT4EumTfNtF+0nebF/4zWOIkCreAbtNqhGEboB6BWrwqNaw4Q==",
|
||||
"dev": true
|
||||
},
|
||||
"extend": {
|
||||
"version": "3.0.2",
|
||||
"resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
|
||||
@ -535,14 +529,22 @@
|
||||
}
|
||||
},
|
||||
"http-proxy": {
|
||||
"version": "1.17.0",
|
||||
"resolved": "https://registry.npmjs.org/http-proxy/-/http-proxy-1.17.0.tgz",
|
||||
"integrity": "sha512-Taqn+3nNvYRfJ3bGvKfBSRwy1v6eePlm3oc/aWVxZp57DQr5Eq3xhKJi7Z4hZpS8PC3H4qI+Yly5EmFacGuA/g==",
|
||||
"version": "1.18.1",
|
||||
"resolved": "https://registry.npmjs.org/http-proxy/-/http-proxy-1.18.1.tgz",
|
||||
"integrity": "sha512-7mz/721AbnJwIVbnaSv1Cz3Am0ZLT/UBwkC92VlxhXv/k/BBQfM2fXElQNC27BVGr0uwUpplYPQM9LnaBMR5NQ==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"eventemitter3": "^3.0.0",
|
||||
"eventemitter3": "^4.0.0",
|
||||
"follow-redirects": "^1.0.0",
|
||||
"requires-port": "^1.0.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"eventemitter3": {
|
||||
"version": "4.0.7",
|
||||
"resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.7.tgz",
|
||||
"integrity": "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==",
|
||||
"dev": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"iconv-lite": {
|
||||
|
||||
@ -57,10 +57,8 @@ filterwarnings =
|
||||
ignore::DeprecationWarning:pyximport.pyximport
|
||||
ignore::PendingDeprecationWarning:sphinx.util.pycompat
|
||||
markers =
|
||||
sphinx
|
||||
apidoc
|
||||
setup_command
|
||||
test_params
|
||||
testpaths = tests
|
||||
|
||||
[coverage:run]
|
||||
|
||||
2
setup.py
2
setup.py
@ -44,7 +44,7 @@ extras_require = {
|
||||
'lint': [
|
||||
'flake8>=3.5.0',
|
||||
'flake8-import-order',
|
||||
'mypy>=0.780',
|
||||
'mypy>=0.790',
|
||||
'docutils-stubs',
|
||||
],
|
||||
'test': [
|
||||
|
||||
@ -32,8 +32,8 @@ if 'PYTHONWARNINGS' not in os.environ:
|
||||
warnings.filterwarnings('ignore', "'U' mode is deprecated",
|
||||
DeprecationWarning, module='docutils.io')
|
||||
|
||||
__version__ = '3.2.2+'
|
||||
__released__ = '3.2.2' # used when Sphinx builds its own docs
|
||||
__version__ = '3.3.0+'
|
||||
__released__ = '3.3.0' # used when Sphinx builds its own docs
|
||||
|
||||
#: Version info for better programmatic use.
|
||||
#:
|
||||
@ -43,7 +43,7 @@ __released__ = '3.2.2' # used when Sphinx builds its own docs
|
||||
#:
|
||||
#: .. versionadded:: 1.2
|
||||
#: Before version 1.2, check the string ``sphinx.__version__``.
|
||||
version_info = (3, 2, 2, 'beta', 0)
|
||||
version_info = (3, 3, 0, 'beta', 0)
|
||||
|
||||
package_dir = path.abspath(path.dirname(__file__))
|
||||
|
||||
|
||||
@ -18,10 +18,11 @@ import warnings
|
||||
from collections import deque
|
||||
from io import StringIO
|
||||
from os import path
|
||||
from typing import Any, Callable, Dict, IO, List, Tuple, Union
|
||||
from typing import Any, Callable, Dict, IO, List, Optional, Tuple, Union
|
||||
|
||||
from docutils import nodes
|
||||
from docutils.nodes import Element, TextElement
|
||||
from docutils.parsers import Parser
|
||||
from docutils.parsers.rst import Directive, roles
|
||||
from docutils.transforms import Transform
|
||||
from pygments.lexer import Lexer
|
||||
@ -293,7 +294,10 @@ class Sphinx:
|
||||
if catalog.domain == 'sphinx' and catalog.is_outdated():
|
||||
catalog.write_mo(self.config.language)
|
||||
|
||||
locale_dirs = [None, path.join(package_dir, 'locale')] + list(repo.locale_dirs)
|
||||
locale_dirs = [None] # type: List[Optional[str]]
|
||||
locale_dirs += list(repo.locale_dirs)
|
||||
locale_dirs += [path.join(package_dir, 'locale')]
|
||||
|
||||
self.translator, has_translation = locale.init(locale_dirs, self.config.language)
|
||||
if has_translation or self.config.language == 'en':
|
||||
# "en" never needs to be translated
|
||||
@ -468,8 +472,10 @@ class Sphinx:
|
||||
def add_builder(self, builder: "Type[Builder]", override: bool = False) -> None:
|
||||
"""Register a new builder.
|
||||
|
||||
*builder* must be a class that inherits from
|
||||
:class:`~sphinx.builders.Builder`.
|
||||
*builder* must be a class that inherits from :class:`~sphinx.builders.Builder`.
|
||||
|
||||
If *override* is True, the given *builder* is forcedly installed even if
|
||||
a builder having the same name is already installed.
|
||||
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
@ -526,6 +532,9 @@ class Sphinx:
|
||||
builtin translator. This allows extensions to use custom translator
|
||||
and define custom nodes for the translator (see :meth:`add_node`).
|
||||
|
||||
If *override* is True, the given *translator_class* is forcedly installed even if
|
||||
a translator for *name* is already installed.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
@ -560,6 +569,9 @@ class Sphinx:
|
||||
Obviously, translators for which you don't specify visitor methods will
|
||||
choke on the node when encountered in a document to translate.
|
||||
|
||||
If *override* is True, the given *node* is forcedly installed even if
|
||||
a node having the same name is already installed.
|
||||
|
||||
.. versionchanged:: 0.5
|
||||
Added the support for keyword arguments giving visit functions.
|
||||
"""
|
||||
@ -595,6 +607,9 @@ class Sphinx:
|
||||
Other keyword arguments are used for node visitor functions. See the
|
||||
:meth:`.Sphinx.add_node` for details.
|
||||
|
||||
If *override* is True, the given *node* is forcedly installed even if
|
||||
a node having the same name is already installed.
|
||||
|
||||
.. versionadded:: 1.4
|
||||
"""
|
||||
self.registry.add_enumerable_node(node, figtype, title_getter, override=override)
|
||||
@ -608,14 +623,14 @@ class Sphinx:
|
||||
details, see `the Docutils docs
|
||||
<http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_ .
|
||||
|
||||
For example, the (already existing) :rst:dir:`literalinclude` directive
|
||||
would be added like this:
|
||||
For example, a custom directive named ``my-directive`` would be added
|
||||
like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from docutils.parsers.rst import Directive, directives
|
||||
|
||||
class LiteralIncludeDirective(Directive):
|
||||
class MyDirective(Directive):
|
||||
has_content = True
|
||||
required_arguments = 1
|
||||
optional_arguments = 0
|
||||
@ -628,7 +643,11 @@ class Sphinx:
|
||||
def run(self):
|
||||
...
|
||||
|
||||
add_directive('literalinclude', LiteralIncludeDirective)
|
||||
def setup(app):
|
||||
add_directive('my-directive', MyDirective)
|
||||
|
||||
If *override* is True, the given *cls* is forcedly installed even if
|
||||
a directive named as *name* is already installed.
|
||||
|
||||
.. versionchanged:: 0.6
|
||||
Docutils 0.5-style directive classes are now supported.
|
||||
@ -652,6 +671,9 @@ class Sphinx:
|
||||
<http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ for
|
||||
more information.
|
||||
|
||||
If *override* is True, the given *role* is forcedly installed even if
|
||||
a role named as *name* is already installed.
|
||||
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
"""
|
||||
@ -667,6 +689,9 @@ class Sphinx:
|
||||
Register a Docutils role that does nothing but wrap its contents in the
|
||||
node given by *nodeclass*.
|
||||
|
||||
If *override* is True, the given *nodeclass* is forcedly installed even if
|
||||
a role named as *name* is already installed.
|
||||
|
||||
.. versionadded:: 0.6
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
@ -686,6 +711,9 @@ class Sphinx:
|
||||
Make the given *domain* (which must be a class; more precisely, a
|
||||
subclass of :class:`~sphinx.domains.Domain`) known to Sphinx.
|
||||
|
||||
If *override* is True, the given *domain* is forcedly installed even if
|
||||
a domain having the same name is already installed.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
@ -699,6 +727,9 @@ class Sphinx:
|
||||
Like :meth:`add_directive`, but the directive is added to the domain
|
||||
named *domain*.
|
||||
|
||||
If *override* is True, the given *directive* is forcedly installed even if
|
||||
a directive named as *name* is already installed.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
@ -712,6 +743,9 @@ class Sphinx:
|
||||
Like :meth:`add_role`, but the role is added to the domain named
|
||||
*domain*.
|
||||
|
||||
If *override* is True, the given *role* is forcedly installed even if
|
||||
a role named as *name* is already installed.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
@ -725,6 +759,9 @@ class Sphinx:
|
||||
Add a custom *index* class to the domain named *domain*. *index* must
|
||||
be a subclass of :class:`~sphinx.domains.Index`.
|
||||
|
||||
If *override* is True, the given *index* is forcedly installed even if
|
||||
an index having the same name is already installed.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
@ -788,6 +825,9 @@ class Sphinx:
|
||||
For the role content, you have the same syntactical possibilities as
|
||||
for standard Sphinx roles (see :ref:`xref-syntax`).
|
||||
|
||||
If *override* is True, the given object_type is forcedly installed even if
|
||||
an object_type having the same name is already installed.
|
||||
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
"""
|
||||
@ -824,6 +864,9 @@ class Sphinx:
|
||||
(Of course, the element following the ``topic`` directive needn't be a
|
||||
section.)
|
||||
|
||||
If *override* is True, the given crossref_type is forcedly installed even if
|
||||
a crossref_type having the same name is already installed.
|
||||
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
"""
|
||||
@ -1004,7 +1047,7 @@ class Sphinx:
|
||||
logger.debug('[app] adding lexer: %r', (alias, lexer))
|
||||
if isinstance(lexer, Lexer):
|
||||
warnings.warn('app.add_lexer() API changed; '
|
||||
'Please give lexer class instead instance',
|
||||
'Please give lexer class instead of instance',
|
||||
RemovedInSphinx40Warning, stacklevel=2)
|
||||
lexers[alias] = lexer
|
||||
else:
|
||||
@ -1019,6 +1062,9 @@ class Sphinx:
|
||||
new types of objects. See the source of the autodoc module for
|
||||
examples on how to subclass :class:`Documenter`.
|
||||
|
||||
If *override* is True, the given *cls* is forcedly installed even if
|
||||
a documenter having the same name is already installed.
|
||||
|
||||
.. todo:: Add real docs for Documenter and subclassing
|
||||
|
||||
.. versionadded:: 0.6
|
||||
@ -1067,13 +1113,19 @@ class Sphinx:
|
||||
Same as :confval:`source_suffix`. The users can override this
|
||||
using the setting.
|
||||
|
||||
If *override* is True, the given *suffix* is forcedly installed even if
|
||||
a same suffix is already installed.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
"""
|
||||
self.registry.add_source_suffix(suffix, filetype, override=override)
|
||||
|
||||
def add_source_parser(self, *args: Any, **kwargs: Any) -> None:
|
||||
def add_source_parser(self, parser: "Type[Parser]", override: bool = False) -> None:
|
||||
"""Register a parser class.
|
||||
|
||||
If *override* is True, the given *parser* is forcedly installed even if
|
||||
a parser for the same suffix is already installed.
|
||||
|
||||
.. versionadded:: 1.4
|
||||
.. versionchanged:: 1.8
|
||||
*suffix* argument is deprecated. It only accepts *parser* argument.
|
||||
@ -1081,7 +1133,7 @@ class Sphinx:
|
||||
.. versionchanged:: 1.8
|
||||
Add *override* keyword.
|
||||
"""
|
||||
self.registry.add_source_parser(*args, **kwargs)
|
||||
self.registry.add_source_parser(parser, override=override)
|
||||
|
||||
def add_env_collector(self, collector: "Type[EnvironmentCollector]") -> None:
|
||||
"""Register an environment collector class.
|
||||
|
||||
@ -208,7 +208,12 @@ class EpubBuilder(StandaloneHTMLBuilder):
|
||||
appeared = set() # type: Set[str]
|
||||
for node in nodes:
|
||||
if node['refuri'] in appeared:
|
||||
logger.warning(__('duplicated ToC entry found: %s'), node['refuri'])
|
||||
logger.warning(
|
||||
__('duplicated ToC entry found: %s'),
|
||||
node['refuri'],
|
||||
type="epub",
|
||||
subtype="duplicated_toc_entry",
|
||||
)
|
||||
else:
|
||||
appeared.add(node['refuri'])
|
||||
|
||||
|
||||
@ -316,7 +316,7 @@ class MessageCatalogBuilder(I18nBuilder):
|
||||
def setup(app: Sphinx) -> Dict[str, Any]:
|
||||
app.add_builder(MessageCatalogBuilder)
|
||||
|
||||
app.add_config_value('gettext_compact', True, 'gettext')
|
||||
app.add_config_value('gettext_compact', True, 'gettext', Any)
|
||||
app.add_config_value('gettext_location', True, 'gettext')
|
||||
app.add_config_value('gettext_uuid', False, 'gettext')
|
||||
app.add_config_value('gettext_auto_build', True, 'env')
|
||||
|
||||
@ -641,17 +641,17 @@ class StandaloneHTMLBuilder(Builder):
|
||||
def gen_additional_pages(self) -> None:
|
||||
# additional pages from conf.py
|
||||
for pagename, template in self.config.html_additional_pages.items():
|
||||
logger.info(' ' + pagename, nonl=True)
|
||||
logger.info(pagename + ' ', nonl=True)
|
||||
self.handle_page(pagename, {}, template)
|
||||
|
||||
# the search page
|
||||
if self.search:
|
||||
logger.info(' search', nonl=True)
|
||||
logger.info('search ', nonl=True)
|
||||
self.handle_page('search', {}, 'search.html')
|
||||
|
||||
# the opensearch xml file
|
||||
if self.config.html_use_opensearch and self.search:
|
||||
logger.info(' opensearch', nonl=True)
|
||||
logger.info('opensearch ', nonl=True)
|
||||
fn = path.join(self.outdir, '_static', 'opensearch.xml')
|
||||
self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn)
|
||||
|
||||
@ -669,7 +669,7 @@ class StandaloneHTMLBuilder(Builder):
|
||||
'genindexcounts': indexcounts,
|
||||
'split_index': self.config.html_split_index,
|
||||
}
|
||||
logger.info(' genindex', nonl=True)
|
||||
logger.info('genindex ', nonl=True)
|
||||
|
||||
if self.config.html_split_index:
|
||||
self.handle_page('genindex', genindexcontext,
|
||||
@ -691,7 +691,7 @@ class StandaloneHTMLBuilder(Builder):
|
||||
'content': content,
|
||||
'collapse_index': collapse,
|
||||
}
|
||||
logger.info(' ' + indexname, nonl=True)
|
||||
logger.info(indexname + ' ', nonl=True)
|
||||
self.handle_page(indexname, indexcontext, 'domainindex.html')
|
||||
|
||||
def copy_image_files(self) -> None:
|
||||
@ -751,18 +751,27 @@ class StandaloneHTMLBuilder(Builder):
|
||||
copyfile(jsfile, path.join(self.outdir, '_static', '_stemmer.js'))
|
||||
|
||||
def copy_theme_static_files(self, context: Dict) -> None:
|
||||
def onerror(filename: str, error: Exception) -> None:
|
||||
logger.warning(__('Failed to copy a file in html_static_file: %s: %r'),
|
||||
filename, error)
|
||||
|
||||
if self.theme:
|
||||
for entry in self.theme.get_theme_dirs()[::-1]:
|
||||
copy_asset(path.join(entry, 'static'),
|
||||
path.join(self.outdir, '_static'),
|
||||
excluded=DOTFILES, context=context, renderer=self.templates)
|
||||
excluded=DOTFILES, context=context,
|
||||
renderer=self.templates, onerror=onerror)
|
||||
|
||||
def copy_html_static_files(self, context: Dict) -> None:
|
||||
def onerror(filename: str, error: Exception) -> None:
|
||||
logger.warning(__('Failed to copy a file in html_static_file: %s: %r'),
|
||||
filename, error)
|
||||
|
||||
excluded = Matcher(self.config.exclude_patterns + ["**/.*"])
|
||||
for entry in self.config.html_static_path:
|
||||
copy_asset(path.join(self.confdir, entry),
|
||||
path.join(self.outdir, '_static'),
|
||||
excluded, context=context, renderer=self.templates)
|
||||
excluded, context=context, renderer=self.templates, onerror=onerror)
|
||||
|
||||
def copy_html_logo(self) -> None:
|
||||
if self.config.html_logo:
|
||||
@ -776,7 +785,7 @@ class StandaloneHTMLBuilder(Builder):
|
||||
|
||||
def copy_static_files(self) -> None:
|
||||
try:
|
||||
with progress_message(__('copying static files... ')):
|
||||
with progress_message(__('copying static files')):
|
||||
ensuredir(path.join(self.outdir, '_static'))
|
||||
|
||||
# prepare context for templates
|
||||
|
||||
@ -24,7 +24,7 @@ from sphinx.builders.latex.constants import ADDITIONAL_SETTINGS, DEFAULT_SETTING
|
||||
from sphinx.builders.latex.theming import Theme, ThemeFactory
|
||||
from sphinx.builders.latex.util import ExtBabel
|
||||
from sphinx.config import Config, ENUM
|
||||
from sphinx.deprecation import RemovedInSphinx40Warning
|
||||
from sphinx.deprecation import RemovedInSphinx40Warning, RemovedInSphinx50Warning
|
||||
from sphinx.environment.adapters.asset import ImageAdapter
|
||||
from sphinx.errors import NoUri, SphinxError
|
||||
from sphinx.locale import _, __
|
||||
@ -128,8 +128,6 @@ class LaTeXBuilder(Builder):
|
||||
self.docnames = [] # type: Iterable[str]
|
||||
self.document_data = [] # type: List[Tuple[str, str, str, str, str, bool]]
|
||||
self.themes = ThemeFactory(self.app)
|
||||
self.usepackages = self.app.registry.latex_packages
|
||||
self.usepackages_after_hyperref = self.app.registry.latex_packages_after_hyperref
|
||||
texescape.init()
|
||||
|
||||
self.init_context()
|
||||
@ -179,10 +177,6 @@ class LaTeXBuilder(Builder):
|
||||
key = (self.config.latex_engine, self.config.language[:2])
|
||||
self.context.update(ADDITIONAL_SETTINGS.get(key, {}))
|
||||
|
||||
# Apply extension settings to context
|
||||
self.context['packages'] = self.usepackages
|
||||
self.context['packages_after_hyperref'] = self.usepackages_after_hyperref
|
||||
|
||||
# Apply user settings to context
|
||||
self.context.update(self.config.latex_elements)
|
||||
self.context['release'] = self.config.release
|
||||
@ -203,6 +197,13 @@ class LaTeXBuilder(Builder):
|
||||
# Show the release label only if release value exists
|
||||
self.context.setdefault('releasename', _('Release'))
|
||||
|
||||
def update_context(self) -> None:
|
||||
"""Update template variables for .tex file just before writing."""
|
||||
# Apply extension settings to context
|
||||
registry = self.app.registry
|
||||
self.context['packages'] = registry.latex_packages
|
||||
self.context['packages_after_hyperref'] = registry.latex_packages_after_hyperref
|
||||
|
||||
def init_babel(self) -> None:
|
||||
self.babel = ExtBabel(self.config.language, not self.context['babel'])
|
||||
if self.config.language and not self.babel.is_supported_language():
|
||||
@ -290,6 +291,7 @@ class LaTeXBuilder(Builder):
|
||||
doctree['tocdepth'] = tocdepth
|
||||
self.post_process_images(doctree)
|
||||
self.update_doc_context(title, author, theme)
|
||||
self.update_context()
|
||||
|
||||
with progress_message(__("writing")):
|
||||
docsettings._author = author
|
||||
@ -448,6 +450,18 @@ class LaTeXBuilder(Builder):
|
||||
filename = path.join(package_dir, 'templates', 'latex', 'sphinxmessages.sty_t')
|
||||
copy_asset_file(filename, self.outdir, context=context, renderer=LaTeXRenderer())
|
||||
|
||||
@property
|
||||
def usepackages(self) -> List[Tuple[str, str]]:
|
||||
warnings.warn('LaTeXBuilder.usepackages is deprecated.',
|
||||
RemovedInSphinx50Warning, stacklevel=2)
|
||||
return self.app.registry.latex_packages
|
||||
|
||||
@property
|
||||
def usepackages_after_hyperref(self) -> List[Tuple[str, str]]:
|
||||
warnings.warn('LaTeXBuilder.usepackages_after_hyperref is deprecated.',
|
||||
RemovedInSphinx50Warning, stacklevel=2)
|
||||
return self.app.registry.latex_packages_after_hyperref
|
||||
|
||||
|
||||
def patch_settings(settings: Any) -> Any:
|
||||
"""Make settings object to show deprecation messages."""
|
||||
@ -503,9 +517,9 @@ def validate_latex_theme_options(app: Sphinx, config: Config) -> None:
|
||||
config.latex_theme_options.pop(key)
|
||||
|
||||
|
||||
def install_pakcages_for_ja(app: Sphinx) -> None:
|
||||
def install_packages_for_ja(app: Sphinx) -> None:
|
||||
"""Install packages for Japanese."""
|
||||
if app.config.language == 'ja':
|
||||
if app.config.language == 'ja' and app.config.latex_engine in ('platex', 'uplatex'):
|
||||
app.add_latex_package('pxjahyper', after_hyperref=True)
|
||||
|
||||
|
||||
@ -556,7 +570,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
|
||||
app.add_builder(LaTeXBuilder)
|
||||
app.connect('config-inited', validate_config_values, priority=800)
|
||||
app.connect('config-inited', validate_latex_theme_options, priority=800)
|
||||
app.connect('builder-inited', install_pakcages_for_ja)
|
||||
app.connect('builder-inited', install_packages_for_ja)
|
||||
|
||||
app.add_config_value('latex_engine', default_latex_engine, None,
|
||||
ENUM('pdflatex', 'xelatex', 'lualatex', 'platex', 'uplatex'))
|
||||
|
||||
@ -106,8 +106,7 @@ class CheckExternalLinksBuilder(Builder):
|
||||
self.rqueue = queue.Queue() # type: queue.Queue
|
||||
self.workers = [] # type: List[threading.Thread]
|
||||
for i in range(self.app.config.linkcheck_workers):
|
||||
thread = threading.Thread(target=self.check_thread)
|
||||
thread.setDaemon(True)
|
||||
thread = threading.Thread(target=self.check_thread, daemon=True)
|
||||
thread.start()
|
||||
self.workers.append(thread)
|
||||
|
||||
@ -166,6 +165,7 @@ class CheckExternalLinksBuilder(Builder):
|
||||
# Read the whole document and see if #anchor exists
|
||||
response = requests.get(req_url, stream=True, config=self.app.config,
|
||||
auth=auth_info, **kwargs)
|
||||
response.raise_for_status()
|
||||
found = check_anchor(response, unquote(anchor))
|
||||
|
||||
if not found:
|
||||
@ -210,16 +210,17 @@ class CheckExternalLinksBuilder(Builder):
|
||||
else:
|
||||
return 'redirected', new_url, 0
|
||||
|
||||
def check() -> Tuple[str, str, int]:
|
||||
def check(docname: str) -> Tuple[str, str, int]:
|
||||
# check for various conditions without bothering the network
|
||||
if len(uri) == 0 or uri.startswith(('#', 'mailto:')):
|
||||
if len(uri) == 0 or uri.startswith(('#', 'mailto:', 'tel:')):
|
||||
return 'unchecked', '', 0
|
||||
elif not uri.startswith(('http:', 'https:')):
|
||||
if uri_re.match(uri):
|
||||
# non supported URI schemes (ex. ftp)
|
||||
return 'unchecked', '', 0
|
||||
else:
|
||||
if path.exists(path.join(self.srcdir, uri)):
|
||||
srcdir = path.dirname(self.env.doc2path(docname))
|
||||
if path.exists(path.join(srcdir, uri)):
|
||||
return 'working', '', 0
|
||||
else:
|
||||
for rex in self.to_ignore:
|
||||
@ -256,7 +257,7 @@ class CheckExternalLinksBuilder(Builder):
|
||||
uri, docname, lineno = self.wqueue.get()
|
||||
if uri is None:
|
||||
break
|
||||
status, info, code = check()
|
||||
status, info, code = check(docname)
|
||||
self.rqueue.put((uri, docname, lineno, status, info, code))
|
||||
|
||||
def process_result(self, result: Tuple[str, str, int, str, str, int]) -> None:
|
||||
|
||||
@ -24,7 +24,7 @@ from sphinx.util import logging
|
||||
from sphinx.util import progress_message
|
||||
from sphinx.util.console import darkgreen # type: ignore
|
||||
from sphinx.util.nodes import inline_all_toctrees
|
||||
from sphinx.util.osutil import make_filename_from_project
|
||||
from sphinx.util.osutil import ensuredir, make_filename_from_project
|
||||
from sphinx.writers.manpage import ManualPageWriter, ManualPageTranslator
|
||||
|
||||
|
||||
@ -80,7 +80,12 @@ class ManualPageBuilder(Builder):
|
||||
docsettings.authors = authors
|
||||
docsettings.section = section
|
||||
|
||||
if self.config.man_make_section_directory:
|
||||
ensuredir(path.join(self.outdir, str(section)))
|
||||
targetname = '%s/%s.%s' % (section, name, section)
|
||||
else:
|
||||
targetname = '%s.%s' % (name, section)
|
||||
|
||||
logger.info(darkgreen(targetname) + ' { ', nonl=True)
|
||||
destination = FileOutput(
|
||||
destination_path=path.join(self.outdir, targetname),
|
||||
@ -115,6 +120,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
|
||||
|
||||
app.add_config_value('man_pages', default_man_pages, None)
|
||||
app.add_config_value('man_show_urls', False, None)
|
||||
app.add_config_value('man_make_section_directory', False, None)
|
||||
|
||||
return {
|
||||
'version': 'builtin',
|
||||
|
||||
@ -489,8 +489,10 @@ def get_parser() -> argparse.ArgumentParser:
|
||||
help=__('project root'))
|
||||
|
||||
group = parser.add_argument_group(__('Structure options'))
|
||||
group.add_argument('--sep', action='store_true', default=None,
|
||||
group.add_argument('--sep', action='store_true', dest='sep', default=None,
|
||||
help=__('if specified, separate source and build dirs'))
|
||||
group.add_argument('--no-sep', action='store_false', dest='sep',
|
||||
help=__('if specified, create build dir under source dir'))
|
||||
group.add_argument('--dot', metavar='DOT', default='_',
|
||||
help=__('replacement for dot in _templates etc.'))
|
||||
|
||||
|
||||
@ -72,7 +72,7 @@ def dedent_lines(lines: List[str], dedent: int, location: Tuple[str, int] = None
|
||||
return lines
|
||||
|
||||
if any(s[:dedent].strip() for s in lines):
|
||||
logger.warning(__('Over dedent has detected'), location=location)
|
||||
logger.warning(__('non-whitespace stripped by dedent'), location=location)
|
||||
|
||||
new_lines = []
|
||||
for line in lines:
|
||||
|
||||
@ -10,9 +10,8 @@
|
||||
|
||||
import re
|
||||
from typing import (
|
||||
Any, Callable, Dict, Generator, Iterator, List, Type, TypeVar, Tuple, Union
|
||||
Any, Callable, cast, Dict, Generator, Iterator, List, Type, TypeVar, Tuple, Union
|
||||
)
|
||||
from typing import cast
|
||||
|
||||
from docutils import nodes
|
||||
from docutils.nodes import Element, Node, TextElement, system_message
|
||||
@ -47,6 +46,11 @@ from sphinx.util.nodes import make_refnode
|
||||
logger = logging.getLogger(__name__)
|
||||
T = TypeVar('T')
|
||||
|
||||
DeclarationType = Union[
|
||||
"ASTStruct", "ASTUnion", "ASTEnum", "ASTEnumerator",
|
||||
"ASTType", "ASTTypeWithInit", "ASTMacro",
|
||||
]
|
||||
|
||||
# https://en.cppreference.com/w/c/keyword
|
||||
_keywords = [
|
||||
'auto', 'break', 'case', 'char', 'const', 'continue', 'default', 'do', 'double',
|
||||
@ -136,8 +140,8 @@ class ASTIdentifier(ASTBaseBase):
|
||||
reftype='identifier',
|
||||
reftarget=targetText, modname=None,
|
||||
classname=None)
|
||||
# key = symbol.get_lookup_key()
|
||||
# pnode['c:parent_key'] = key
|
||||
key = symbol.get_lookup_key()
|
||||
pnode['c:parent_key'] = key
|
||||
if self.is_anon():
|
||||
pnode += nodes.strong(text="[anonymous]")
|
||||
else:
|
||||
@ -636,6 +640,10 @@ class ASTFunctionParameter(ASTBase):
|
||||
self.arg = arg
|
||||
self.ellipsis = ellipsis
|
||||
|
||||
def get_id(self, version: int, objectType: str, symbol: "Symbol") -> str:
|
||||
# the anchor will be our parent
|
||||
return symbol.parent.declaration.get_id(version, prefixed=False)
|
||||
|
||||
def _stringify(self, transform: StringifyTransform) -> str:
|
||||
if self.ellipsis:
|
||||
return '...'
|
||||
@ -1149,6 +1157,9 @@ class ASTType(ASTBase):
|
||||
def name(self) -> ASTNestedName:
|
||||
return self.decl.name
|
||||
|
||||
def get_id(self, version: int, objectType: str, symbol: "Symbol") -> str:
|
||||
return symbol.get_full_nested_name().get_id(version)
|
||||
|
||||
@property
|
||||
def function_params(self) -> List[ASTFunctionParameter]:
|
||||
return self.decl.function_params
|
||||
@ -1191,6 +1202,9 @@ class ASTTypeWithInit(ASTBase):
|
||||
def name(self) -> ASTNestedName:
|
||||
return self.type.name
|
||||
|
||||
def get_id(self, version: int, objectType: str, symbol: "Symbol") -> str:
|
||||
return self.type.get_id(version, objectType, symbol)
|
||||
|
||||
def _stringify(self, transform: StringifyTransform) -> str:
|
||||
res = []
|
||||
res.append(transform(self.type))
|
||||
@ -1242,6 +1256,9 @@ class ASTMacro(ASTBase):
|
||||
def name(self) -> ASTNestedName:
|
||||
return self.ident
|
||||
|
||||
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.ident))
|
||||
@ -1342,7 +1359,8 @@ class ASTEnumerator(ASTBase):
|
||||
|
||||
|
||||
class ASTDeclaration(ASTBaseBase):
|
||||
def __init__(self, objectType: str, directiveType: str, declaration: Any,
|
||||
def __init__(self, objectType: str, directiveType: str,
|
||||
declaration: Union[DeclarationType, ASTFunctionParameter],
|
||||
semicolon: bool = False) -> None:
|
||||
self.objectType = objectType
|
||||
self.directiveType = directiveType
|
||||
@ -1359,18 +1377,20 @@ class ASTDeclaration(ASTBaseBase):
|
||||
|
||||
@property
|
||||
def name(self) -> ASTNestedName:
|
||||
return self.declaration.name
|
||||
decl = cast(DeclarationType, self.declaration)
|
||||
return decl.name
|
||||
|
||||
@property
|
||||
def function_params(self) -> List[ASTFunctionParameter]:
|
||||
if self.objectType != 'function':
|
||||
return None
|
||||
return self.declaration.function_params
|
||||
decl = cast(ASTType, self.declaration)
|
||||
return decl.function_params
|
||||
|
||||
def get_id(self, version: int, prefixed: bool = True) -> str:
|
||||
if self.objectType == 'enumerator' and self.enumeratorScopedSymbol:
|
||||
return self.enumeratorScopedSymbol.declaration.get_id(version, prefixed)
|
||||
id_ = self.symbol.get_full_nested_name().get_id(version)
|
||||
id_ = self.declaration.get_id(version, self.objectType, self.symbol)
|
||||
if prefixed:
|
||||
return _id_prefix[version] + id_
|
||||
else:
|
||||
@ -1413,7 +1433,8 @@ class ASTDeclaration(ASTBaseBase):
|
||||
elif self.objectType == 'enumerator':
|
||||
mainDeclNode += addnodes.desc_annotation('enumerator ', 'enumerator ')
|
||||
elif self.objectType == 'type':
|
||||
prefix = self.declaration.get_type_declaration_prefix()
|
||||
decl = cast(ASTType, self.declaration)
|
||||
prefix = decl.get_type_declaration_prefix()
|
||||
prefix += ' '
|
||||
mainDeclNode += addnodes.desc_annotation(prefix, prefix)
|
||||
else:
|
||||
@ -1562,6 +1583,11 @@ class Symbol:
|
||||
for s in sChild.get_all_symbols():
|
||||
yield s
|
||||
|
||||
@property
|
||||
def children(self) -> Iterator["Symbol"]:
|
||||
for c in self._children:
|
||||
yield c
|
||||
|
||||
@property
|
||||
def children_recurse_anon(self) -> Iterator["Symbol"]:
|
||||
for c in self._children:
|
||||
@ -1792,7 +1818,7 @@ class Symbol:
|
||||
|
||||
if not declaration:
|
||||
if Symbol.debug_lookup:
|
||||
Symbol.debug_print("no delcaration")
|
||||
Symbol.debug_print("no declaration")
|
||||
Symbol.debug_indent -= 2
|
||||
# good, just a scope creation
|
||||
# TODO: what if we have more than one symbol?
|
||||
@ -2983,7 +3009,7 @@ class DefinitionParser(BaseParser):
|
||||
|
||||
def parse_pre_v3_type_definition(self) -> ASTDeclaration:
|
||||
self.skip_ws()
|
||||
declaration = None # type: Any
|
||||
declaration = None # type: DeclarationType
|
||||
if self.skip_word('struct'):
|
||||
typ = 'struct'
|
||||
declaration = self._parse_struct()
|
||||
@ -3006,7 +3032,7 @@ class DefinitionParser(BaseParser):
|
||||
'macro', 'struct', 'union', 'enum', 'enumerator', 'type'):
|
||||
raise Exception('Internal error, unknown directiveType "%s".' % directiveType)
|
||||
|
||||
declaration = None # type: Any
|
||||
declaration = None # type: DeclarationType
|
||||
if objectType == 'member':
|
||||
declaration = self._parse_type_with_init(named=True, outer='member')
|
||||
elif objectType == 'function':
|
||||
@ -3153,10 +3179,6 @@ class CObject(ObjectDescription):
|
||||
|
||||
self.state.document.note_explicit_target(signode)
|
||||
|
||||
domain = cast(CDomain, self.env.get_domain('c'))
|
||||
if name not in domain.objects:
|
||||
domain.objects[name] = (domain.env.docname, newestId, self.objtype)
|
||||
|
||||
if 'noindexentry' not in self.options:
|
||||
indexText = self.get_index_text(name)
|
||||
self.indexnode['entries'].append(('single', indexText, newestId, '', None))
|
||||
@ -3408,10 +3430,13 @@ class CNamespacePopObject(SphinxDirective):
|
||||
|
||||
|
||||
class AliasNode(nodes.Element):
|
||||
def __init__(self, sig: str, env: "BuildEnvironment" = None,
|
||||
def __init__(self, sig: str, maxdepth: int, document: Any, env: "BuildEnvironment" = None,
|
||||
parentKey: LookupKey = None) -> None:
|
||||
super().__init__()
|
||||
self.sig = sig
|
||||
self.maxdepth = maxdepth
|
||||
assert maxdepth >= 0
|
||||
self.document = document
|
||||
if env is not None:
|
||||
if 'c:parent_symbol' not in env.temp_data:
|
||||
root = env.domaindata['c']['root_symbol']
|
||||
@ -3428,6 +3453,37 @@ class AliasNode(nodes.Element):
|
||||
class AliasTransform(SphinxTransform):
|
||||
default_priority = ReferencesResolver.default_priority - 1
|
||||
|
||||
def _render_symbol(self, s: Symbol, maxdepth: int, document: Any) -> List[Node]:
|
||||
nodes = [] # type: List[Node]
|
||||
options = dict() # type: ignore
|
||||
signode = addnodes.desc_signature('', '')
|
||||
nodes.append(signode)
|
||||
s.declaration.describe_signature(signode, 'markName', self.env, options)
|
||||
if maxdepth == 0:
|
||||
recurse = True
|
||||
elif maxdepth == 1:
|
||||
recurse = False
|
||||
else:
|
||||
maxdepth -= 1
|
||||
recurse = True
|
||||
if recurse:
|
||||
content = addnodes.desc_content()
|
||||
desc = addnodes.desc()
|
||||
content.append(desc)
|
||||
desc.document = document
|
||||
desc['domain'] = 'c'
|
||||
# 'desctype' is a backwards compatible attribute
|
||||
desc['objtype'] = desc['desctype'] = 'alias'
|
||||
desc['noindex'] = True
|
||||
|
||||
for sChild in s.children:
|
||||
childNodes = self._render_symbol(sChild, maxdepth, document)
|
||||
desc.extend(childNodes)
|
||||
|
||||
if len(desc.children) != 0:
|
||||
nodes.append(content)
|
||||
return nodes
|
||||
|
||||
def apply(self, **kwargs: Any) -> None:
|
||||
for node in self.document.traverse(AliasNode):
|
||||
sig = node.sig
|
||||
@ -3468,17 +3524,16 @@ class AliasTransform(SphinxTransform):
|
||||
logger.warning("Could not find C declaration for alias '%s'." % name,
|
||||
location=node)
|
||||
node.replace_self(signode)
|
||||
else:
|
||||
nodes = []
|
||||
options = dict() # type: ignore
|
||||
signode = addnodes.desc_signature(sig, '')
|
||||
nodes.append(signode)
|
||||
s.declaration.describe_signature(signode, 'markName', self.env, options)
|
||||
continue
|
||||
|
||||
nodes = self._render_symbol(s, maxdepth=node.maxdepth, document=node.document)
|
||||
node.replace_self(nodes)
|
||||
|
||||
|
||||
class CAliasObject(ObjectDescription):
|
||||
option_spec = {} # type: Dict
|
||||
option_spec = {
|
||||
'maxdepth': directives.nonnegative_int
|
||||
} # type: Dict
|
||||
|
||||
def run(self) -> List[Node]:
|
||||
if ':' in self.name:
|
||||
@ -3494,16 +3549,10 @@ class CAliasObject(ObjectDescription):
|
||||
node['noindex'] = True
|
||||
|
||||
self.names = [] # type: List[str]
|
||||
maxdepth = self.options.get('maxdepth', 1)
|
||||
signatures = self.get_signatures()
|
||||
for i, sig in enumerate(signatures):
|
||||
node.append(AliasNode(sig, env=self.env))
|
||||
|
||||
contentnode = addnodes.desc_content()
|
||||
node.append(contentnode)
|
||||
self.before_content()
|
||||
self.state.nested_parse(self.content, self.content_offset, contentnode)
|
||||
self.env.temp_data['object'] = None
|
||||
self.after_content()
|
||||
node.append(AliasNode(sig, maxdepth, self.state.document, env=self.env))
|
||||
return [node]
|
||||
|
||||
|
||||
@ -3607,6 +3656,10 @@ class CDomain(Domain):
|
||||
'macro': ObjType(_('macro'), 'macro'),
|
||||
'type': ObjType(_('type'), 'type'),
|
||||
'var': ObjType(_('variable'), 'data'),
|
||||
'enum': ObjType(_('enum'), 'enum'),
|
||||
'enumerator': ObjType(_('enumerator'), 'enumerator'),
|
||||
'struct': ObjType(_('struct'), 'struct'),
|
||||
'union': ObjType(_('union'), 'union'),
|
||||
}
|
||||
|
||||
directives = {
|
||||
@ -3645,10 +3698,6 @@ class CDomain(Domain):
|
||||
'objects': {}, # fullname -> docname, node_id, objtype
|
||||
} # type: Dict[str, Union[Symbol, Dict[str, Tuple[str, str, str]]]]
|
||||
|
||||
@property
|
||||
def objects(self) -> Dict[str, Tuple[str, str, str]]:
|
||||
return self.data.setdefault('objects', {}) # fullname -> docname, node_id, objtype
|
||||
|
||||
def clear_doc(self, docname: str) -> None:
|
||||
if Symbol.debug_show_tree:
|
||||
print("clear_doc:", docname)
|
||||
@ -3664,9 +3713,6 @@ class CDomain(Domain):
|
||||
print(self.data['root_symbol'].dump(1))
|
||||
print("\tafter end")
|
||||
print("clear_doc end:", docname)
|
||||
for fullname, (fn, _id, _l) in list(self.objects.items()):
|
||||
if fn == docname:
|
||||
del self.objects[fullname]
|
||||
|
||||
def process_doc(self, env: BuildEnvironment, docname: str,
|
||||
document: nodes.document) -> None:
|
||||
@ -3752,8 +3798,18 @@ class CDomain(Domain):
|
||||
return []
|
||||
|
||||
def get_objects(self) -> Iterator[Tuple[str, str, str, str, str, int]]:
|
||||
for refname, (docname, node_id, objtype) in list(self.objects.items()):
|
||||
yield (refname, refname, objtype, docname, node_id, 1)
|
||||
rootSymbol = self.data['root_symbol']
|
||||
for symbol in rootSymbol.get_all_symbols():
|
||||
if symbol.declaration is None:
|
||||
continue
|
||||
assert symbol.docname
|
||||
fullNestedName = symbol.get_full_nested_name()
|
||||
name = str(fullNestedName).lstrip('.')
|
||||
dispname = fullNestedName.get_display_string().lstrip('.')
|
||||
objectType = symbol.declaration.objectType
|
||||
docname = symbol.docname
|
||||
newestId = symbol.declaration.get_newest_id()
|
||||
yield (name, dispname, objectType, docname, newestId, 1)
|
||||
|
||||
|
||||
def setup(app: Sphinx) -> Dict[str, Any]:
|
||||
|
||||
@ -1836,7 +1836,7 @@ class ASTFunctionParameter(ASTBase):
|
||||
# this is not part of the normal name mangling in C++
|
||||
if symbol:
|
||||
# the anchor will be our parent
|
||||
return symbol.parent.declaration.get_id(version, prefixed=None)
|
||||
return symbol.parent.declaration.get_id(version, prefixed=False)
|
||||
# else, do the usual
|
||||
if self.ellipsis:
|
||||
return 'z'
|
||||
@ -4107,7 +4107,7 @@ class Symbol:
|
||||
Symbol.debug_print("self:")
|
||||
print(self.to_string(Symbol.debug_indent + 1), end="")
|
||||
Symbol.debug_print("nestedName: ", nestedName)
|
||||
Symbol.debug_print("templateDecls: ", templateDecls)
|
||||
Symbol.debug_print("templateDecls: ", ",".join(str(t) for t in templateDecls))
|
||||
Symbol.debug_print("strictTemplateParamArgLists:", strictTemplateParamArgLists)
|
||||
Symbol.debug_print("ancestorLookupType:", ancestorLookupType)
|
||||
Symbol.debug_print("templateShorthand: ", templateShorthand)
|
||||
@ -4231,7 +4231,7 @@ class Symbol:
|
||||
Symbol.debug_indent += 1
|
||||
Symbol.debug_print("_add_symbols:")
|
||||
Symbol.debug_indent += 1
|
||||
Symbol.debug_print("tdecls:", templateDecls)
|
||||
Symbol.debug_print("tdecls:", ",".join(str(t) for t in templateDecls))
|
||||
Symbol.debug_print("nn: ", nestedName)
|
||||
Symbol.debug_print("decl: ", declaration)
|
||||
Symbol.debug_print("doc: ", docname)
|
||||
@ -4292,7 +4292,7 @@ class Symbol:
|
||||
|
||||
if not declaration:
|
||||
if Symbol.debug_lookup:
|
||||
Symbol.debug_print("no delcaration")
|
||||
Symbol.debug_print("no declaration")
|
||||
Symbol.debug_indent -= 2
|
||||
# good, just a scope creation
|
||||
# TODO: what if we have more than one symbol?
|
||||
@ -4360,6 +4360,11 @@ class Symbol:
|
||||
if Symbol.debug_lookup:
|
||||
Symbol.debug_print("candId:", candId)
|
||||
for symbol in withDecl:
|
||||
# but all existing must be functions as well,
|
||||
# otherwise we declare it to be a duplicate
|
||||
if symbol.declaration.objectType != 'function':
|
||||
handleDuplicateDeclaration(symbol, candSymbol)
|
||||
# (not reachable)
|
||||
oldId = symbol.declaration.get_newest_id()
|
||||
if Symbol.debug_lookup:
|
||||
Symbol.debug_print("oldId: ", oldId)
|
||||
@ -4370,7 +4375,11 @@ class Symbol:
|
||||
# if there is an empty symbol, fill that one
|
||||
if len(noDecl) == 0:
|
||||
if Symbol.debug_lookup:
|
||||
Symbol.debug_print("no match, no empty, candSybmol is not None?:", candSymbol is not None) # NOQA
|
||||
Symbol.debug_print("no match, no empty")
|
||||
if candSymbol is not None:
|
||||
Symbol.debug_print("result is already created candSymbol")
|
||||
else:
|
||||
Symbol.debug_print("result is makeCandSymbol()")
|
||||
Symbol.debug_indent -= 2
|
||||
if candSymbol is not None:
|
||||
return candSymbol
|
||||
@ -6814,10 +6823,12 @@ class CPPObject(ObjectDescription):
|
||||
parentSymbol = env.temp_data['cpp:parent_symbol']
|
||||
parentDecl = parentSymbol.declaration
|
||||
if parentDecl is not None and parentDecl.objectType == 'function':
|
||||
logger.warning("C++ declarations inside functions are not supported." +
|
||||
" Parent function is " +
|
||||
msg = "C++ declarations inside functions are not supported." \
|
||||
" Parent function: {}\nDirective name: {}\nDirective arg: {}"
|
||||
logger.warning(msg.format(
|
||||
str(parentSymbol.get_full_nested_name()),
|
||||
location=self.get_source_info())
|
||||
self.name, self.arguments[0]
|
||||
), location=self.get_source_info())
|
||||
name = _make_phony_error_name()
|
||||
symbol = parentSymbol.add_name(name)
|
||||
env.temp_data['cpp:last_symbol'] = symbol
|
||||
|
||||
@ -500,7 +500,8 @@ class ProductionList(SphinxDirective):
|
||||
except ValueError:
|
||||
break
|
||||
subnode = addnodes.production(rule)
|
||||
subnode['tokenname'] = name.strip()
|
||||
name = name.strip()
|
||||
subnode['tokenname'] = name
|
||||
if subnode['tokenname']:
|
||||
prefix = 'grammar-token-%s' % productionGroup
|
||||
node_id = make_id(self.env, self.state.document, prefix, name)
|
||||
|
||||
@ -224,6 +224,10 @@ class TocTreeCollector(EnvironmentCollector):
|
||||
def get_figtype(node: Node) -> str:
|
||||
for domain in env.domains.values():
|
||||
figtype = domain.get_enumerable_node_type(node)
|
||||
if domain.name == 'std' and not domain.get_numfig_title(node): # type: ignore
|
||||
# Skip if uncaptioned node
|
||||
continue
|
||||
|
||||
if figtype:
|
||||
return figtype
|
||||
|
||||
|
||||
@ -94,6 +94,9 @@ def members_option(arg: Any) -> Union[object, List[str]]:
|
||||
"""Used to convert the :members: option to auto directives."""
|
||||
if arg is None or arg is True:
|
||||
return ALL
|
||||
elif arg is False:
|
||||
return None
|
||||
else:
|
||||
return [x.strip() for x in arg.split(',') if x.strip()]
|
||||
|
||||
|
||||
@ -172,7 +175,7 @@ def merge_members_option(options: Dict) -> None:
|
||||
|
||||
members = options.setdefault('members', [])
|
||||
for key in {'private-members', 'special-members'}:
|
||||
if key in options and options[key] is not ALL:
|
||||
if key in options and options[key] not in (ALL, None):
|
||||
for member in options[key]:
|
||||
if member not in members:
|
||||
members.append(member)
|
||||
@ -532,6 +535,11 @@ class Documenter:
|
||||
self.env.app.emit('autodoc-process-docstring',
|
||||
self.objtype, self.fullname, self.object,
|
||||
self.options, docstringlines)
|
||||
|
||||
if docstringlines and docstringlines[-1] != '':
|
||||
# append a blank line to the end of the docstring
|
||||
docstringlines.append('')
|
||||
|
||||
yield from docstringlines
|
||||
|
||||
def get_sourcename(self) -> str:
|
||||
@ -1205,7 +1213,8 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ
|
||||
|
||||
try:
|
||||
self.env.app.emit('autodoc-before-process-signature', self.object, False)
|
||||
sig = inspect.signature(self.object, follow_wrapped=True)
|
||||
sig = inspect.signature(self.object, follow_wrapped=True,
|
||||
type_aliases=self.env.config.autodoc_type_aliases)
|
||||
args = stringify_signature(sig, **kwargs)
|
||||
except TypeError as exc:
|
||||
logger.warning(__("Failed to get a function signature for %s: %s"),
|
||||
@ -1231,7 +1240,9 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ
|
||||
|
||||
def format_signature(self, **kwargs: Any) -> str:
|
||||
sigs = []
|
||||
if self.analyzer and '.'.join(self.objpath) in self.analyzer.overloads:
|
||||
if (self.analyzer and
|
||||
'.'.join(self.objpath) in self.analyzer.overloads and
|
||||
self.env.config.autodoc_typehints == 'signature'):
|
||||
# Use signatures for overloaded functions instead of the implementation function.
|
||||
overloaded = True
|
||||
else:
|
||||
@ -1254,7 +1265,9 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ
|
||||
if overloaded:
|
||||
__globals__ = safe_getattr(self.object, '__globals__', {})
|
||||
for overload in self.analyzer.overloads.get('.'.join(self.objpath)):
|
||||
overload = evaluate_signature(overload, __globals__)
|
||||
overload = evaluate_signature(overload, __globals__,
|
||||
self.env.config.autodoc_type_aliases)
|
||||
|
||||
sig = stringify_signature(overload, **kwargs)
|
||||
sigs.append(sig)
|
||||
|
||||
@ -1263,7 +1276,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ
|
||||
def annotate_to_first_argument(self, func: Callable, typ: Type) -> None:
|
||||
"""Annotate type hint to the first argument of function if needed."""
|
||||
try:
|
||||
sig = inspect.signature(func)
|
||||
sig = inspect.signature(func, type_aliases=self.env.config.autodoc_type_aliases)
|
||||
except TypeError as exc:
|
||||
logger.warning(__("Failed to get a function signature for %s: %s"),
|
||||
self.fullname, exc)
|
||||
@ -1291,6 +1304,11 @@ class SingledispatchFunctionDocumenter(FunctionDocumenter):
|
||||
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 DecoratorDocumenter(FunctionDocumenter):
|
||||
"""
|
||||
@ -1317,6 +1335,12 @@ _METACLASS_CALL_BLACKLIST = [
|
||||
]
|
||||
|
||||
|
||||
# Types whose __new__ signature is a pass-thru.
|
||||
_CLASS_NEW_BLACKLIST = [
|
||||
'typing.Generic.__new__',
|
||||
]
|
||||
|
||||
|
||||
class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type: ignore
|
||||
"""
|
||||
Specialized Documenter subclass for classes.
|
||||
@ -1378,17 +1402,24 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
|
||||
if call is not None:
|
||||
self.env.app.emit('autodoc-before-process-signature', call, True)
|
||||
try:
|
||||
sig = inspect.signature(call, bound_method=True)
|
||||
sig = inspect.signature(call, bound_method=True,
|
||||
type_aliases=self.env.config.autodoc_type_aliases)
|
||||
return type(self.object), '__call__', sig
|
||||
except ValueError:
|
||||
pass
|
||||
|
||||
# Now we check if the 'obj' class has a '__new__' method
|
||||
new = get_user_defined_function_or_method(self.object, '__new__')
|
||||
|
||||
if new is not None:
|
||||
if "{0.__module__}.{0.__qualname__}".format(new) in _CLASS_NEW_BLACKLIST:
|
||||
new = None
|
||||
|
||||
if new is not None:
|
||||
self.env.app.emit('autodoc-before-process-signature', new, True)
|
||||
try:
|
||||
sig = inspect.signature(new, bound_method=True)
|
||||
sig = inspect.signature(new, bound_method=True,
|
||||
type_aliases=self.env.config.autodoc_type_aliases)
|
||||
return self.object, '__new__', sig
|
||||
except ValueError:
|
||||
pass
|
||||
@ -1398,7 +1429,8 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
|
||||
if init is not None:
|
||||
self.env.app.emit('autodoc-before-process-signature', init, True)
|
||||
try:
|
||||
sig = inspect.signature(init, bound_method=True)
|
||||
sig = inspect.signature(init, bound_method=True,
|
||||
type_aliases=self.env.config.autodoc_type_aliases)
|
||||
return self.object, '__init__', sig
|
||||
except ValueError:
|
||||
pass
|
||||
@ -1409,7 +1441,8 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
|
||||
# the signature from, so just pass the object itself to our hook.
|
||||
self.env.app.emit('autodoc-before-process-signature', self.object, False)
|
||||
try:
|
||||
sig = inspect.signature(self.object, bound_method=False)
|
||||
sig = inspect.signature(self.object, bound_method=False,
|
||||
type_aliases=self.env.config.autodoc_type_aliases)
|
||||
return None, None, sig
|
||||
except ValueError:
|
||||
pass
|
||||
@ -1440,23 +1473,16 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
|
||||
return ''
|
||||
|
||||
sig = super().format_signature()
|
||||
|
||||
overloaded = False
|
||||
qualname = None
|
||||
# TODO: recreate analyzer for the module of class (To be clear, owner of the method)
|
||||
if self._signature_class and self._signature_method_name and self.analyzer:
|
||||
qualname = '.'.join([self._signature_class.__qualname__,
|
||||
self._signature_method_name])
|
||||
if qualname in self.analyzer.overloads:
|
||||
overloaded = True
|
||||
|
||||
sigs = []
|
||||
if overloaded:
|
||||
|
||||
overloads = self.get_overloaded_signatures()
|
||||
if overloads and self.env.config.autodoc_typehints == 'signature':
|
||||
# Use signatures for overloaded methods instead of the implementation method.
|
||||
method = safe_getattr(self._signature_class, self._signature_method_name, None)
|
||||
__globals__ = safe_getattr(method, '__globals__', {})
|
||||
for overload in self.analyzer.overloads.get(qualname):
|
||||
overload = evaluate_signature(overload, __globals__)
|
||||
for overload in overloads:
|
||||
overload = evaluate_signature(overload, __globals__,
|
||||
self.env.config.autodoc_type_aliases)
|
||||
|
||||
parameters = list(overload.parameters.values())
|
||||
overload = overload.replace(parameters=parameters[1:],
|
||||
@ -1468,6 +1494,20 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
|
||||
|
||||
return "\n".join(sigs)
|
||||
|
||||
def get_overloaded_signatures(self) -> List[Signature]:
|
||||
if self._signature_class and self._signature_method_name:
|
||||
for cls in self._signature_class.__mro__:
|
||||
try:
|
||||
analyzer = ModuleAnalyzer.for_module(cls.__module__)
|
||||
analyzer.parse()
|
||||
qualname = '.'.join([cls.__qualname__, self._signature_method_name])
|
||||
if qualname in analyzer.overloads:
|
||||
return analyzer.overloads.get(qualname)
|
||||
except PycodeError:
|
||||
pass
|
||||
|
||||
return []
|
||||
|
||||
def add_directive_header(self, sig: str) -> None:
|
||||
sourcename = self.get_sourcename()
|
||||
|
||||
@ -1704,7 +1744,8 @@ class GenericAliasDocumenter(DataDocumenter):
|
||||
return inspect.isgenericalias(member)
|
||||
|
||||
def add_directive_header(self, sig: str) -> None:
|
||||
self.options.annotation = SUPPRESS # type: ignore
|
||||
self.options = Options(self.options)
|
||||
self.options['annotation'] = SUPPRESS
|
||||
super().add_directive_header(sig)
|
||||
|
||||
def add_content(self, more_content: Any, no_docstring: bool = False) -> None:
|
||||
@ -1725,10 +1766,11 @@ class TypeVarDocumenter(DataDocumenter):
|
||||
@classmethod
|
||||
def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
|
||||
) -> bool:
|
||||
return isinstance(member, TypeVar) and isattr # type: ignore
|
||||
return isinstance(member, TypeVar) and isattr
|
||||
|
||||
def add_directive_header(self, sig: str) -> None:
|
||||
self.options.annotation = SUPPRESS # type: ignore
|
||||
self.options = Options(self.options)
|
||||
self.options['annotation'] = SUPPRESS
|
||||
super().add_directive_header(sig)
|
||||
|
||||
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
|
||||
@ -1801,11 +1843,13 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
|
||||
else:
|
||||
if inspect.isstaticmethod(self.object, cls=self.parent, name=self.object_name):
|
||||
self.env.app.emit('autodoc-before-process-signature', self.object, False)
|
||||
sig = inspect.signature(self.object, bound_method=False)
|
||||
sig = inspect.signature(self.object, bound_method=False,
|
||||
type_aliases=self.env.config.autodoc_type_aliases)
|
||||
else:
|
||||
self.env.app.emit('autodoc-before-process-signature', self.object, True)
|
||||
sig = inspect.signature(self.object, bound_method=True,
|
||||
follow_wrapped=True)
|
||||
follow_wrapped=True,
|
||||
type_aliases=self.env.config.autodoc_type_aliases)
|
||||
args = stringify_signature(sig, **kwargs)
|
||||
except TypeError as exc:
|
||||
logger.warning(__("Failed to get a method signature for %s: %s"),
|
||||
@ -1840,7 +1884,9 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
|
||||
|
||||
def format_signature(self, **kwargs: Any) -> str:
|
||||
sigs = []
|
||||
if self.analyzer and '.'.join(self.objpath) in self.analyzer.overloads:
|
||||
if (self.analyzer and
|
||||
'.'.join(self.objpath) in self.analyzer.overloads and
|
||||
self.env.config.autodoc_typehints == 'signature'):
|
||||
# Use signatures for overloaded methods instead of the implementation method.
|
||||
overloaded = True
|
||||
else:
|
||||
@ -1865,7 +1911,9 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
|
||||
if overloaded:
|
||||
__globals__ = safe_getattr(self.object, '__globals__', {})
|
||||
for overload in self.analyzer.overloads.get('.'.join(self.objpath)):
|
||||
overload = evaluate_signature(overload, __globals__)
|
||||
overload = evaluate_signature(overload, __globals__,
|
||||
self.env.config.autodoc_type_aliases)
|
||||
|
||||
if not inspect.isstaticmethod(self.object, cls=self.parent,
|
||||
name=self.object_name):
|
||||
parameters = list(overload.parameters.values())
|
||||
@ -1878,7 +1926,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
|
||||
def annotate_to_first_argument(self, func: Callable, typ: Type) -> None:
|
||||
"""Annotate type hint to the first argument of function if needed."""
|
||||
try:
|
||||
sig = inspect.signature(func)
|
||||
sig = inspect.signature(func, type_aliases=self.env.config.autodoc_type_aliases)
|
||||
except TypeError as exc:
|
||||
logger.warning(__("Failed to get a method signature for %s: %s"),
|
||||
self.fullname, exc)
|
||||
@ -1905,6 +1953,11 @@ class SingledispatchMethodDocumenter(MethodDocumenter):
|
||||
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 AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): # type: ignore
|
||||
"""
|
||||
@ -2218,6 +2271,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
|
||||
app.add_config_value('autodoc_mock_imports', [], True)
|
||||
app.add_config_value('autodoc_typehints', "signature", True,
|
||||
ENUM("signature", "description", "none"))
|
||||
app.add_config_value('autodoc_type_aliases', {}, True)
|
||||
app.add_config_value('autodoc_warningiserror', True, True)
|
||||
app.add_config_value('autodoc_inherit_docstrings', True, True)
|
||||
app.add_event('autodoc-before-process-signature')
|
||||
|
||||
@ -206,7 +206,10 @@ def get_object_members(subject: Any, objpath: List[str], attrgetter: Callable,
|
||||
if isclass(subject) and getattr(subject, '__slots__', None) is not None:
|
||||
from sphinx.ext.autodoc import SLOTSATTR
|
||||
|
||||
for name in subject.__slots__:
|
||||
slots = subject.__slots__
|
||||
if isinstance(slots, str):
|
||||
slots = [slots]
|
||||
for name in slots:
|
||||
members[name] = Attribute(name, True, SLOTSATTR)
|
||||
|
||||
# other members
|
||||
|
||||
@ -66,6 +66,10 @@ module_sig_re = re.compile(r'''^(?:([\w.]*)\.)? # module names
|
||||
''', re.VERBOSE)
|
||||
|
||||
|
||||
py_builtins = [obj for obj in vars(builtins).values()
|
||||
if inspect.isclass(obj)]
|
||||
|
||||
|
||||
def try_import(objname: str) -> Any:
|
||||
"""Import a object or module using *name* and *currentmodule*.
|
||||
*name* should be a relative name from *currentmodule* or
|
||||
@ -178,7 +182,6 @@ class InheritanceGraph:
|
||||
traverse to. Multiple names can be specified separated by comma.
|
||||
"""
|
||||
all_classes = {}
|
||||
py_builtins = vars(builtins).values()
|
||||
|
||||
def recurse(cls: Any) -> None:
|
||||
if not show_builtins and cls in py_builtins:
|
||||
|
||||
@ -31,12 +31,12 @@ logger = logging.getLogger(__name__)
|
||||
|
||||
_directive_regex = re.compile(r'\.\. \S+::')
|
||||
_google_section_regex = re.compile(r'^(\s|\w)+:\s*$')
|
||||
_google_typed_arg_regex = re.compile(r'\s*(.+?)\s*\(\s*(.*[^\s]+)\s*\)')
|
||||
_google_typed_arg_regex = re.compile(r'(.+?)\(\s*(.*[^\s]+)\s*\)')
|
||||
_numpy_section_regex = re.compile(r'^[=\-`:\'"~^_*+#<>]{2,}\s*$')
|
||||
_single_colon_regex = re.compile(r'(?<!:):(?!:)')
|
||||
_xref_or_code_regex = re.compile(
|
||||
r'((?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:`.+?`)|'
|
||||
r'(?:``.+``))')
|
||||
r'(?:``.+?``))')
|
||||
_xref_regex = re.compile(
|
||||
r'(?:(?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:)?`.+?`)'
|
||||
)
|
||||
@ -254,7 +254,7 @@ class GoogleDocstring:
|
||||
if parse_type:
|
||||
match = _google_typed_arg_regex.match(before)
|
||||
if match:
|
||||
_name = match.group(1)
|
||||
_name = match.group(1).strip()
|
||||
_type = match.group(2)
|
||||
|
||||
_name = self._escape_args_and_kwargs(_name)
|
||||
@ -699,6 +699,9 @@ class GoogleDocstring:
|
||||
m = self._name_rgx.match(_type)
|
||||
if m and m.group('name'):
|
||||
_type = m.group('name')
|
||||
elif _xref_regex.match(_type):
|
||||
pos = _type.find('`')
|
||||
_type = _type[pos + 1:-1]
|
||||
_type = ' ' + _type if _type else ''
|
||||
_desc = self._strip_empty(_desc)
|
||||
_descs = ' ' + '\n '.join(_desc) if any(_desc) else ''
|
||||
@ -1104,6 +1107,10 @@ class NumpyDocstring(GoogleDocstring):
|
||||
_name, _type = line, ''
|
||||
_name, _type = _name.strip(), _type.strip()
|
||||
_name = self._escape_args_and_kwargs(_name)
|
||||
|
||||
if prefer_type and not _type:
|
||||
_type, _name = _name, _type
|
||||
|
||||
if self._config.napoleon_preprocess_types:
|
||||
_type = _convert_numpy_type_spec(
|
||||
_type,
|
||||
@ -1111,8 +1118,6 @@ class NumpyDocstring(GoogleDocstring):
|
||||
translations=self._config.napoleon_type_aliases or {},
|
||||
)
|
||||
|
||||
if prefer_type and not _type:
|
||||
_type, _name = _name, _type
|
||||
indent = self._get_indent(line) + 1
|
||||
_desc = self._dedent(self._consume_indented_block(indent))
|
||||
_desc = self.__class__(_desc, self._config).lines()
|
||||
@ -1188,6 +1193,22 @@ class NumpyDocstring(GoogleDocstring):
|
||||
items.append((name, list(rest), role))
|
||||
del rest[:]
|
||||
|
||||
def translate(func, description, role):
|
||||
translations = self._config.napoleon_type_aliases
|
||||
if role is not None or not translations:
|
||||
return func, description, role
|
||||
|
||||
translated = translations.get(func, func)
|
||||
match = self._name_rgx.match(translated)
|
||||
if not match:
|
||||
return translated, description, role
|
||||
|
||||
groups = match.groupdict()
|
||||
role = groups["role"]
|
||||
new_func = groups["name"] or groups["name2"]
|
||||
|
||||
return new_func, description, role
|
||||
|
||||
current_func = None
|
||||
rest = [] # type: List[str]
|
||||
|
||||
@ -1218,37 +1239,19 @@ class NumpyDocstring(GoogleDocstring):
|
||||
if not items:
|
||||
return []
|
||||
|
||||
roles = {
|
||||
'method': 'meth',
|
||||
'meth': 'meth',
|
||||
'function': 'func',
|
||||
'func': 'func',
|
||||
'class': 'class',
|
||||
'exception': 'exc',
|
||||
'exc': 'exc',
|
||||
'object': 'obj',
|
||||
'obj': 'obj',
|
||||
'module': 'mod',
|
||||
'mod': 'mod',
|
||||
'data': 'data',
|
||||
'constant': 'const',
|
||||
'const': 'const',
|
||||
'attribute': 'attr',
|
||||
'attr': 'attr'
|
||||
}
|
||||
if self._what is None:
|
||||
func_role = 'obj'
|
||||
else:
|
||||
func_role = roles.get(self._what, '')
|
||||
# apply type aliases
|
||||
items = [
|
||||
translate(func, description, role)
|
||||
for func, description, role in items
|
||||
]
|
||||
|
||||
lines = [] # type: List[str]
|
||||
last_had_desc = True
|
||||
for func, desc, role in items:
|
||||
for name, desc, role in items:
|
||||
if role:
|
||||
link = ':%s:`%s`' % (role, func)
|
||||
elif func_role:
|
||||
link = ':%s:`%s`' % (func_role, func)
|
||||
link = ':%s:`%s`' % (role, name)
|
||||
else:
|
||||
link = "`%s`_" % func
|
||||
link = ':obj:`%s`' % name
|
||||
if desc or last_had_desc:
|
||||
lines += ['']
|
||||
lines += [link]
|
||||
|
||||
@ -106,7 +106,7 @@ class _TranslationProxy(UserString):
|
||||
translators = defaultdict(NullTranslations) # type: Dict[Tuple[str, str], NullTranslations]
|
||||
|
||||
|
||||
def init(locale_dirs: List[str], language: str,
|
||||
def init(locale_dirs: List[Optional[str]], language: str,
|
||||
catalog: str = 'sphinx', namespace: str = 'general') -> Tuple[NullTranslations, bool]:
|
||||
"""Look for message catalogs in `locale_dirs` and *ensure* that there is at
|
||||
least a NullTranslations catalog set in `translators`. If called multiple
|
||||
|
||||
@ -58,17 +58,19 @@ def parse(code: str, mode: str = 'exec') -> "ast.AST":
|
||||
return ast.parse(code, mode=mode)
|
||||
|
||||
|
||||
def unparse(node: Optional[ast.AST]) -> Optional[str]:
|
||||
def unparse(node: Optional[ast.AST], code: str = '') -> Optional[str]:
|
||||
"""Unparse an AST to string."""
|
||||
if node is None:
|
||||
return None
|
||||
elif isinstance(node, str):
|
||||
return node
|
||||
return _UnparseVisitor().visit(node)
|
||||
return _UnparseVisitor(code).visit(node)
|
||||
|
||||
|
||||
# a greatly cut-down version of `ast._Unparser`
|
||||
class _UnparseVisitor(ast.NodeVisitor):
|
||||
def __init__(self, code: str = '') -> None:
|
||||
self.code = code
|
||||
|
||||
def _visit_op(self, node: ast.AST) -> str:
|
||||
return OPERATORS[node.__class__]
|
||||
@ -166,6 +168,20 @@ class _UnparseVisitor(ast.NodeVisitor):
|
||||
return "{" + ", ".join(self.visit(e) for e in node.elts) + "}"
|
||||
|
||||
def visit_Subscript(self, node: ast.Subscript) -> str:
|
||||
def is_simple_tuple(value: ast.AST) -> bool:
|
||||
return (
|
||||
isinstance(value, ast.Tuple) and
|
||||
bool(value.elts) and
|
||||
not any(isinstance(elt, ast.Starred) for elt in value.elts)
|
||||
)
|
||||
|
||||
if is_simple_tuple(node.slice):
|
||||
elts = ", ".join(self.visit(e) for e in node.slice.elts) # type: ignore
|
||||
return "%s[%s]" % (self.visit(node.value), elts)
|
||||
elif isinstance(node.slice, ast.Index) and is_simple_tuple(node.slice.value):
|
||||
elts = ", ".join(self.visit(e) for e in node.slice.value.elts) # type: ignore
|
||||
return "%s[%s]" % (self.visit(node.value), elts)
|
||||
else:
|
||||
return "%s[%s]" % (self.visit(node.value), self.visit(node.slice))
|
||||
|
||||
def visit_UnaryOp(self, node: ast.UnaryOp) -> str:
|
||||
@ -173,7 +189,7 @@ class _UnparseVisitor(ast.NodeVisitor):
|
||||
|
||||
def visit_Tuple(self, node: ast.Tuple) -> str:
|
||||
if node.elts:
|
||||
return ", ".join(self.visit(e) for e in node.elts)
|
||||
return "(" + ", ".join(self.visit(e) for e in node.elts) + ")"
|
||||
else:
|
||||
return "()"
|
||||
|
||||
@ -181,6 +197,11 @@ class _UnparseVisitor(ast.NodeVisitor):
|
||||
def visit_Constant(self, node: ast.Constant) -> str:
|
||||
if node.value is Ellipsis:
|
||||
return "..."
|
||||
elif isinstance(node.value, (int, float, complex)):
|
||||
if self.code and sys.version_info > (3, 8):
|
||||
return ast.get_source_segment(self.code, node)
|
||||
else:
|
||||
return repr(node.value)
|
||||
else:
|
||||
return repr(node.value)
|
||||
|
||||
|
||||
@ -259,12 +259,12 @@ class SphinxComponentRegistry:
|
||||
else:
|
||||
self.source_suffix[suffix] = filetype
|
||||
|
||||
def add_source_parser(self, parser: "Type[Parser]", **kwargs: Any) -> None:
|
||||
def add_source_parser(self, parser: "Type[Parser]", override: bool = False) -> None:
|
||||
logger.debug('[app] adding search source_parser: %r', parser)
|
||||
|
||||
# create a map from filetype to parser
|
||||
for filetype in parser.supported:
|
||||
if filetype in self.source_parsers and not kwargs.get('override'):
|
||||
if filetype in self.source_parsers and not override:
|
||||
raise ExtensionError(__('source_parser for %r is already registered') %
|
||||
filetype)
|
||||
else:
|
||||
@ -367,7 +367,14 @@ class SphinxComponentRegistry:
|
||||
logger.debug('[app] adding js_file: %r, %r', filename, attributes)
|
||||
self.js_files.append((filename, attributes))
|
||||
|
||||
def has_latex_package(self, name: str) -> bool:
|
||||
packages = self.latex_packages + self.latex_packages_after_hyperref
|
||||
return bool([x for x in packages if x[0] == name])
|
||||
|
||||
def add_latex_package(self, name: str, options: str, after_hyperref: bool = False) -> None:
|
||||
if self.has_latex_package(name):
|
||||
logger.warn("latex package '%s' already included" % name)
|
||||
|
||||
logger.debug('[app] adding latex package: %r', name)
|
||||
if after_hyperref:
|
||||
self.latex_packages_after_hyperref.append((name, options))
|
||||
@ -394,7 +401,7 @@ class SphinxComponentRegistry:
|
||||
|
||||
def load_extension(self, app: "Sphinx", extname: str) -> None:
|
||||
"""Load a Sphinx extension."""
|
||||
if extname in app.extensions: # alread loaded
|
||||
if extname in app.extensions: # already loaded
|
||||
return
|
||||
if extname in EXTENSION_BLACKLIST:
|
||||
logger.warning(__('the extension %r was already merged with Sphinx since '
|
||||
|
||||
@ -297,8 +297,8 @@ class IndexBuilder:
|
||||
frozen.get('envversion') != self.env.version:
|
||||
raise ValueError('old format')
|
||||
index2fn = frozen['docnames']
|
||||
self._filenames = dict(zip(index2fn, frozen['filenames'])) # type: ignore
|
||||
self._titles = dict(zip(index2fn, frozen['titles'])) # type: ignore
|
||||
self._filenames = dict(zip(index2fn, frozen['filenames']))
|
||||
self._titles = dict(zip(index2fn, frozen['titles']))
|
||||
|
||||
def load_terms(mapping: Dict[str, Any]) -> Dict[str, Set[str]]:
|
||||
rv = {}
|
||||
@ -359,13 +359,13 @@ class IndexBuilder:
|
||||
def get_terms(self, fn2index: Dict) -> Tuple[Dict[str, List[str]], Dict[str, List[str]]]:
|
||||
rvs = {}, {} # type: Tuple[Dict[str, List[str]], Dict[str, List[str]]]
|
||||
for rv, mapping in zip(rvs, (self._mapping, self._title_mapping)):
|
||||
for k, v in mapping.items(): # type: ignore
|
||||
for k, v in mapping.items():
|
||||
if len(v) == 1:
|
||||
fn, = v
|
||||
if fn in fn2index:
|
||||
rv[k] = fn2index[fn] # type: ignore
|
||||
rv[k] = fn2index[fn]
|
||||
else:
|
||||
rv[k] = sorted([fn2index[fn] for fn in v if fn in fn2index]) # type: ignore # NOQA
|
||||
rv[k] = sorted([fn2index[fn] for fn in v if fn in fn2index])
|
||||
return rvs
|
||||
|
||||
def freeze(self) -> Dict[str, Any]:
|
||||
|
||||
@ -22,6 +22,21 @@ from sphinx.testing import util
|
||||
from sphinx.testing.util import SphinxTestApp, SphinxTestAppWrapperForSkipBuilding
|
||||
|
||||
|
||||
DEFAULT_ENABLED_MARKERS = [
|
||||
(
|
||||
'sphinx(builder, testroot=None, freshenv=False, confoverrides=None, tags=None,'
|
||||
' docutilsconf=None, parallel=0): arguments to initialize the sphinx test application.'
|
||||
),
|
||||
'test_params(shared_result=...): test parameters.',
|
||||
]
|
||||
|
||||
|
||||
def pytest_configure(config):
|
||||
# register custom markers
|
||||
for marker in DEFAULT_ENABLED_MARKERS:
|
||||
config.addinivalue_line('markers', marker)
|
||||
|
||||
|
||||
@pytest.fixture(scope='session')
|
||||
def rootdir() -> str:
|
||||
return None
|
||||
|
||||
@ -21,7 +21,6 @@ from docutils.nodes import Node
|
||||
from docutils.parsers.rst import directives, roles
|
||||
|
||||
from sphinx import application, locale
|
||||
from sphinx.builders.latex import LaTeXBuilder
|
||||
from sphinx.deprecation import RemovedInSphinx40Warning
|
||||
from sphinx.pycode import ModuleAnalyzer
|
||||
from sphinx.testing.path import path
|
||||
@ -109,7 +108,7 @@ class SphinxTestApp(application.Sphinx):
|
||||
|
||||
def __init__(self, buildername: str = 'html', srcdir: path = None, freshenv: bool = False,
|
||||
confoverrides: Dict = None, status: IO = None, warning: IO = None,
|
||||
tags: List[str] = None, docutilsconf: str = None) -> None:
|
||||
tags: List[str] = None, docutilsconf: str = None, parallel: int = 0) -> None:
|
||||
|
||||
if docutilsconf is not None:
|
||||
(srcdir / 'docutils.conf').write_text(docutilsconf)
|
||||
@ -134,14 +133,13 @@ class SphinxTestApp(application.Sphinx):
|
||||
try:
|
||||
super().__init__(srcdir, confdir, outdir, doctreedir,
|
||||
buildername, confoverrides, status, warning,
|
||||
freshenv, warningiserror, tags)
|
||||
freshenv, warningiserror, tags, parallel=parallel)
|
||||
except Exception:
|
||||
self.cleanup()
|
||||
raise
|
||||
|
||||
def cleanup(self, doctrees: bool = False) -> None:
|
||||
ModuleAnalyzer.cache.clear()
|
||||
LaTeXBuilder.usepackages = []
|
||||
locale.translators.clear()
|
||||
sys.path[:] = self._saved_path
|
||||
sys.modules.pop('autodoc_fodder', None)
|
||||
|
||||
@ -588,12 +588,14 @@
|
||||
{% classes with \chapter command
|
||||
\fancypagestyle{normal}{
|
||||
\fancyhf{}
|
||||
% FIXME: this presupposes "twoside".
|
||||
% If "oneside" class option, there are warnings in LaTeX log.
|
||||
\fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
|
||||
\fancyfoot[RO]{{\py@HeaderFamily\thepage}}
|
||||
\fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
|
||||
\fancyhead[RO]{{\py@HeaderFamily \@title\sphinxheadercomma\py@release}}
|
||||
\if@twoside
|
||||
\fancyfoot[LE]{{\py@HeaderFamily\thepage}}
|
||||
\fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
|
||||
\fancyhead[LE,RO]{{\py@HeaderFamily \@title\sphinxheadercomma\py@release}}
|
||||
\fancyhead[LE]{{\py@HeaderFamily \@title\sphinxheadercomma\py@release}}
|
||||
\fi
|
||||
\renewcommand{\headrulewidth}{0.4pt}
|
||||
\renewcommand{\footrulewidth}{0.4pt}
|
||||
% define chaptermark with \@chappos when \@chappos is available for Japanese
|
||||
@ -605,7 +607,8 @@
|
||||
% page of a chapter `clean.'
|
||||
\fancypagestyle{plain}{
|
||||
\fancyhf{}
|
||||
\fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
|
||||
\fancyfoot[RO]{{\py@HeaderFamily\thepage}}
|
||||
\if@twoside\fancyfoot[LE]{{\py@HeaderFamily\thepage}}\fi
|
||||
\renewcommand{\headrulewidth}{0pt}
|
||||
\renewcommand{\footrulewidth}{0.4pt}
|
||||
}
|
||||
|
||||
@ -95,8 +95,8 @@
|
||||
{%- endmacro %}
|
||||
|
||||
{%- macro css() %}
|
||||
<link rel="stylesheet" href="{{ pathto('_static/' + style, 1)|e }}" type="text/css" />
|
||||
<link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
|
||||
<link rel="stylesheet" href="{{ pathto('_static/' + style, 1)|e }}" type="text/css" />
|
||||
{%- for css in css_files %}
|
||||
{%- if css|attr("filename") %}
|
||||
{{ css_tag(css) }}
|
||||
|
||||
@ -764,6 +764,7 @@ div.code-block-caption code {
|
||||
}
|
||||
|
||||
table.highlighttable td.linenos,
|
||||
span.linenos,
|
||||
div.doctest > div.highlight span.gp { /* gp: Generic.Prompt */
|
||||
user-select: none;
|
||||
}
|
||||
|
||||
@ -285,9 +285,10 @@ var Documentation = {
|
||||
initOnKeyListeners: function() {
|
||||
$(document).keydown(function(event) {
|
||||
var activeElementType = document.activeElement.tagName;
|
||||
// don't navigate when in search box or textarea
|
||||
// don't navigate when in search box, textarea, dropdown or button
|
||||
if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT'
|
||||
&& !event.altKey && !event.ctrlKey && !event.metaKey && !event.shiftKey) {
|
||||
&& activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey
|
||||
&& !event.shiftKey) {
|
||||
switch (event.keyCode) {
|
||||
case 37: // left
|
||||
var prevHref = $('link[rel="prev"]').prop('href');
|
||||
|
||||
@ -59,10 +59,10 @@ var Search = {
|
||||
_pulse_status : -1,
|
||||
|
||||
htmlToText : function(htmlString) {
|
||||
var htmlElement = document.createElement('span');
|
||||
htmlElement.innerHTML = htmlString;
|
||||
$(htmlElement).find('.headerlink').remove();
|
||||
docContent = $(htmlElement).find('[role=main]')[0];
|
||||
var virtualDocument = document.implementation.createHTMLDocument('virtual');
|
||||
var htmlElement = $(htmlString, virtualDocument);
|
||||
htmlElement.find('.headerlink').remove();
|
||||
docContent = htmlElement.find('[role=main]')[0];
|
||||
if(docContent === undefined) {
|
||||
console.warn("Content block not found. Sphinx search tries to obtain it " +
|
||||
"via '[role=main]'. Could you check your theme or template.");
|
||||
|
||||
@ -11,7 +11,7 @@
|
||||
import os
|
||||
import re
|
||||
from math import ceil
|
||||
from typing import Any, Dict, List, Tuple
|
||||
from typing import Any, Dict, List, Optional, Tuple
|
||||
|
||||
from docutils import nodes
|
||||
|
||||
@ -175,6 +175,13 @@ class ImageConverter(BaseImageConverter):
|
||||
"""
|
||||
default_priority = 200
|
||||
|
||||
#: The converter is available or not. Will be filled at the first call of
|
||||
#: the build. The result is shared in the same process.
|
||||
#:
|
||||
#: .. todo:: This should be refactored not to store the state without class
|
||||
#: variable.
|
||||
available = None # type: Optional[bool]
|
||||
|
||||
#: A conversion rules the image converter supports.
|
||||
#: It is represented as a list of pair of source image format (mimetype) and
|
||||
#: destination one::
|
||||
@ -187,16 +194,14 @@ class ImageConverter(BaseImageConverter):
|
||||
conversion_rules = [] # type: List[Tuple[str, str]]
|
||||
|
||||
def __init__(self, *args: Any, **kwargs: Any) -> None:
|
||||
self.available = None # type: bool
|
||||
# the converter is available or not.
|
||||
# Will be checked at first conversion
|
||||
super().__init__(*args, **kwargs)
|
||||
|
||||
def match(self, node: nodes.image) -> bool:
|
||||
if not self.app.builder.supported_image_types:
|
||||
return False
|
||||
elif self.available is None:
|
||||
self.available = self.is_available()
|
||||
# store the value to the class variable to share it during the build
|
||||
self.__class__.available = self.is_available()
|
||||
|
||||
if not self.available:
|
||||
return False
|
||||
|
||||
@ -10,7 +10,7 @@
|
||||
|
||||
import os
|
||||
import posixpath
|
||||
from typing import Dict
|
||||
from typing import Callable, Dict
|
||||
|
||||
from docutils.utils import relative_path
|
||||
|
||||
@ -56,7 +56,8 @@ def copy_asset_file(source: str, destination: str,
|
||||
|
||||
|
||||
def copy_asset(source: str, destination: str, excluded: PathMatcher = lambda path: False,
|
||||
context: Dict = None, renderer: "BaseRenderer" = None) -> None:
|
||||
context: Dict = None, renderer: "BaseRenderer" = None,
|
||||
onerror: Callable[[str, Exception], None] = None) -> None:
|
||||
"""Copy asset files to destination recursively.
|
||||
|
||||
On copying, it expands the template variables if context argument is given and
|
||||
@ -67,6 +68,7 @@ def copy_asset(source: str, destination: str, excluded: PathMatcher = lambda pat
|
||||
:param excluded: The matcher to determine the given path should be copied or not
|
||||
:param context: The template variables. If not given, template files are simply copied
|
||||
:param renderer: The template engine. If not given, SphinxRenderer is used by default
|
||||
:param onerror: The error handler.
|
||||
"""
|
||||
if not os.path.exists(source):
|
||||
return
|
||||
@ -90,6 +92,12 @@ def copy_asset(source: str, destination: str, excluded: PathMatcher = lambda pat
|
||||
|
||||
for filename in files:
|
||||
if not excluded(posixpath.join(reldir, filename)):
|
||||
try:
|
||||
copy_asset_file(posixpath.join(root, filename),
|
||||
posixpath.join(destination, reldir),
|
||||
context, renderer)
|
||||
except Exception as exc:
|
||||
if onerror:
|
||||
onerror(posixpath.join(root, filename), exc)
|
||||
else:
|
||||
raise
|
||||
|
||||
@ -14,7 +14,7 @@ import warnings
|
||||
from collections import namedtuple
|
||||
from datetime import datetime, timezone
|
||||
from os import path
|
||||
from typing import Callable, Generator, List, Set, Tuple
|
||||
from typing import Callable, Generator, List, Set, Tuple, Union
|
||||
|
||||
import babel.dates
|
||||
from babel.messages.mofile import write_mo
|
||||
@ -128,8 +128,10 @@ def find_catalog(docname: str, compaction: bool) -> str:
|
||||
return ret
|
||||
|
||||
|
||||
def docname_to_domain(docname: str, compation: bool) -> str:
|
||||
def docname_to_domain(docname: str, compation: Union[bool, str]) -> str:
|
||||
"""Convert docname to domain for catalogs."""
|
||||
if isinstance(compation, str):
|
||||
return compation
|
||||
if compation:
|
||||
return docname.split(SEP, 1)[0]
|
||||
else:
|
||||
|
||||
@ -304,6 +304,11 @@ def iscoroutinefunction(obj: Any) -> bool:
|
||||
|
||||
def isproperty(obj: Any) -> bool:
|
||||
"""Check if the object is property."""
|
||||
if sys.version_info > (3, 8):
|
||||
from functools import cached_property # cached_property is available since py3.8
|
||||
if isinstance(obj, cached_property):
|
||||
return True
|
||||
|
||||
return isinstance(obj, property)
|
||||
|
||||
|
||||
@ -434,8 +439,8 @@ def _should_unwrap(subject: Callable) -> bool:
|
||||
return False
|
||||
|
||||
|
||||
def signature(subject: Callable, bound_method: bool = False, follow_wrapped: bool = False
|
||||
) -> inspect.Signature:
|
||||
def signature(subject: Callable, bound_method: bool = False, follow_wrapped: bool = False,
|
||||
type_aliases: Dict = {}) -> inspect.Signature:
|
||||
"""Return a Signature object for the given *subject*.
|
||||
|
||||
:param bound_method: Specify *subject* is a bound method or not
|
||||
@ -465,7 +470,7 @@ def signature(subject: Callable, bound_method: bool = False, follow_wrapped: boo
|
||||
|
||||
try:
|
||||
# Update unresolved annotations using ``get_type_hints()``.
|
||||
annotations = typing.get_type_hints(subject)
|
||||
annotations = typing.get_type_hints(subject, None, type_aliases)
|
||||
for i, param in enumerate(parameters):
|
||||
if isinstance(param.annotation, str) and param.name in annotations:
|
||||
parameters[i] = param.replace(annotation=annotations[param.name])
|
||||
@ -595,13 +600,14 @@ def stringify_signature(sig: inspect.Signature, show_annotation: bool = True,
|
||||
|
||||
def signature_from_str(signature: str) -> inspect.Signature:
|
||||
"""Create a Signature object from string."""
|
||||
module = ast.parse('def func' + signature + ': pass')
|
||||
code = 'def func' + signature + ': pass'
|
||||
module = ast.parse(code)
|
||||
function = cast(ast.FunctionDef, module.body[0]) # type: ignore
|
||||
|
||||
return signature_from_ast(function)
|
||||
return signature_from_ast(function, code)
|
||||
|
||||
|
||||
def signature_from_ast(node: ast.FunctionDef) -> inspect.Signature:
|
||||
def signature_from_ast(node: ast.FunctionDef, code: str = '') -> inspect.Signature:
|
||||
"""Create a Signature object from AST *node*."""
|
||||
args = node.args
|
||||
defaults = list(args.defaults)
|
||||
@ -621,9 +627,9 @@ def signature_from_ast(node: ast.FunctionDef) -> inspect.Signature:
|
||||
if defaults[i] is Parameter.empty:
|
||||
default = Parameter.empty
|
||||
else:
|
||||
default = ast_unparse(defaults[i])
|
||||
default = ast_unparse(defaults[i], code)
|
||||
|
||||
annotation = ast_unparse(arg.annotation) or Parameter.empty
|
||||
annotation = ast_unparse(arg.annotation, code) or Parameter.empty
|
||||
params.append(Parameter(arg.arg, Parameter.POSITIONAL_ONLY,
|
||||
default=default, annotation=annotation))
|
||||
|
||||
@ -631,29 +637,29 @@ def signature_from_ast(node: ast.FunctionDef) -> inspect.Signature:
|
||||
if defaults[i + posonlyargs] is Parameter.empty:
|
||||
default = Parameter.empty
|
||||
else:
|
||||
default = ast_unparse(defaults[i + posonlyargs])
|
||||
default = ast_unparse(defaults[i + posonlyargs], code)
|
||||
|
||||
annotation = ast_unparse(arg.annotation) or Parameter.empty
|
||||
annotation = ast_unparse(arg.annotation, code) or Parameter.empty
|
||||
params.append(Parameter(arg.arg, Parameter.POSITIONAL_OR_KEYWORD,
|
||||
default=default, annotation=annotation))
|
||||
|
||||
if args.vararg:
|
||||
annotation = ast_unparse(args.vararg.annotation) or Parameter.empty
|
||||
annotation = ast_unparse(args.vararg.annotation, code) or Parameter.empty
|
||||
params.append(Parameter(args.vararg.arg, Parameter.VAR_POSITIONAL,
|
||||
annotation=annotation))
|
||||
|
||||
for i, arg in enumerate(args.kwonlyargs):
|
||||
default = ast_unparse(args.kw_defaults[i]) or Parameter.empty
|
||||
annotation = ast_unparse(arg.annotation) or Parameter.empty
|
||||
default = ast_unparse(args.kw_defaults[i], code) or Parameter.empty
|
||||
annotation = ast_unparse(arg.annotation, code) or Parameter.empty
|
||||
params.append(Parameter(arg.arg, Parameter.KEYWORD_ONLY, default=default,
|
||||
annotation=annotation))
|
||||
|
||||
if args.kwarg:
|
||||
annotation = ast_unparse(args.kwarg.annotation) or Parameter.empty
|
||||
annotation = ast_unparse(args.kwarg.annotation, code) or Parameter.empty
|
||||
params.append(Parameter(args.kwarg.arg, Parameter.VAR_KEYWORD,
|
||||
annotation=annotation))
|
||||
|
||||
return_annotation = ast_unparse(node.returns) or Parameter.empty
|
||||
return_annotation = ast_unparse(node.returns, code) or Parameter.empty
|
||||
|
||||
return inspect.Signature(params, return_annotation=return_annotation)
|
||||
|
||||
|
||||
@ -122,11 +122,16 @@ class InventoryFile:
|
||||
|
||||
for line in stream.read_compressed_lines():
|
||||
# be careful to handle names with embedded spaces correctly
|
||||
m = re.match(r'(?x)(.+?)\s+(\S*:\S*)\s+(-?\d+)\s+?(\S*)\s+(.*)',
|
||||
m = re.match(r'(?x)(.+?)\s+(\S+)\s+(-?\d+)\s+?(\S*)\s+(.*)',
|
||||
line.rstrip())
|
||||
if not m:
|
||||
continue
|
||||
name, type, prio, location, dispname = m.groups()
|
||||
if ':' not in type:
|
||||
# wrong type value. type should be in the form of "{domain}:{objtype}"
|
||||
#
|
||||
# Note: To avoid the regex DoS, this is implemented in python (refs: #8175)
|
||||
continue
|
||||
if type == 'py:module' and type in invdata and name in invdata[type]:
|
||||
# due to a bug in 1.1 and below,
|
||||
# two inventory entries are created
|
||||
|
||||
@ -84,6 +84,8 @@ class LaTeXRenderer(SphinxRenderer):
|
||||
self.env.variable_end_string = '%>'
|
||||
self.env.block_start_string = '<%'
|
||||
self.env.block_end_string = '%>'
|
||||
self.env.comment_start_string = '<#'
|
||||
self.env.comment_end_string = '#>'
|
||||
|
||||
|
||||
class ReSTRenderer(SphinxRenderer):
|
||||
|
||||
@ -57,14 +57,18 @@ Inventory = Dict[str, Dict[str, Tuple[str, str, str, str]]]
|
||||
def is_system_TypeVar(typ: Any) -> bool:
|
||||
"""Check *typ* is system defined TypeVar."""
|
||||
modname = getattr(typ, '__module__', '')
|
||||
return modname == 'typing' and isinstance(typ, TypeVar) # type: ignore
|
||||
return modname == 'typing' and isinstance(typ, TypeVar)
|
||||
|
||||
|
||||
def stringify(annotation: Any) -> str:
|
||||
"""Stringify type annotation object."""
|
||||
if isinstance(annotation, str):
|
||||
if annotation.startswith("'") and annotation.endswith("'"):
|
||||
# might be a double Forward-ref'ed type. Go unquoting.
|
||||
return annotation[1:-2]
|
||||
else:
|
||||
return annotation
|
||||
elif isinstance(annotation, TypeVar): # type: ignore
|
||||
elif isinstance(annotation, TypeVar):
|
||||
return annotation.__name__
|
||||
elif not annotation:
|
||||
return repr(annotation)
|
||||
@ -105,7 +109,10 @@ def _stringify_py37(annotation: Any) -> str:
|
||||
return repr(annotation)
|
||||
|
||||
if getattr(annotation, '__args__', None):
|
||||
if qualname == 'Union':
|
||||
if not isinstance(annotation.__args__, (list, tuple)):
|
||||
# broken __args__ found
|
||||
pass
|
||||
elif qualname == 'Union':
|
||||
if len(annotation.__args__) > 1 and annotation.__args__[-1] is NoneType:
|
||||
if len(annotation.__args__) > 2:
|
||||
args = ', '.join(stringify(a) for a in annotation.__args__[:-1])
|
||||
|
||||
@ -450,7 +450,7 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
|
||||
|
||||
highlighted = self.highlighter.highlight_block(
|
||||
node.rawsource, lang, opts=opts, linenos=linenos,
|
||||
location=(self.builder.current_docname, node.line), **highlight_args
|
||||
location=node, **highlight_args
|
||||
)
|
||||
starttag = self.starttag(node, 'div', suffix='',
|
||||
CLASS='highlight-%s notranslate' % lang)
|
||||
|
||||
@ -402,7 +402,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
|
||||
|
||||
highlighted = self.highlighter.highlight_block(
|
||||
node.rawsource, lang, opts=opts, linenos=linenos,
|
||||
location=(self.builder.current_docname, node.line), **highlight_args
|
||||
location=node, **highlight_args
|
||||
)
|
||||
starttag = self.starttag(node, 'div', suffix='',
|
||||
CLASS='highlight-%s notranslate' % lang)
|
||||
|
||||
@ -651,7 +651,7 @@ class LaTeXTranslator(SphinxTranslator):
|
||||
if len(node.children) != 1 and not isinstance(node.children[0],
|
||||
nodes.Text):
|
||||
logger.warning(__('document title is not a single Text node'),
|
||||
location=(self.curfilestack[-1], node.line))
|
||||
location=node)
|
||||
if not self.elements['title']:
|
||||
# text needs to be escaped since it is inserted into
|
||||
# the output literally
|
||||
@ -684,7 +684,7 @@ class LaTeXTranslator(SphinxTranslator):
|
||||
else:
|
||||
logger.warning(__('encountered title node not in section, topic, table, '
|
||||
'admonition or sidebar'),
|
||||
location=(self.curfilestack[-1], node.line or ''))
|
||||
location=node)
|
||||
self.body.append('\\sphinxstyleothertitle{')
|
||||
self.context.append('}\n')
|
||||
self.in_title = 1
|
||||
@ -1762,7 +1762,7 @@ class LaTeXTranslator(SphinxTranslator):
|
||||
|
||||
hlcode = self.highlighter.highlight_block(
|
||||
node.rawsource, lang, opts=opts, linenos=linenos,
|
||||
location=(self.curfilestack[-1], node.line), **highlight_args
|
||||
location=node, **highlight_args
|
||||
)
|
||||
if self.in_footnote:
|
||||
self.body.append('\n\\sphinxSetupCodeBlockInFootnote')
|
||||
|
||||
@ -369,7 +369,7 @@ class TexinfoTranslator(SphinxTranslator):
|
||||
"""Return an escaped string suitable for use as an argument
|
||||
to a Texinfo command."""
|
||||
s = self.escape(s)
|
||||
# commas are the argument delimeters
|
||||
# commas are the argument delimiters
|
||||
s = s.replace(',', '@comma{}')
|
||||
# normalize white space
|
||||
s = ' '.join(s.split()).strip()
|
||||
@ -628,7 +628,7 @@ class TexinfoTranslator(SphinxTranslator):
|
||||
elif not isinstance(parent, nodes.section):
|
||||
logger.warning(__('encountered title node not in section, topic, table, '
|
||||
'admonition or sidebar'),
|
||||
location=(self.curfilestack[-1], node.line))
|
||||
location=node)
|
||||
self.visit_rubric(node)
|
||||
else:
|
||||
try:
|
||||
@ -1186,7 +1186,7 @@ class TexinfoTranslator(SphinxTranslator):
|
||||
self.body.append('\n@caption{')
|
||||
else:
|
||||
logger.warning(__('caption not inside a figure.'),
|
||||
location=(self.curfilestack[-1], node.line))
|
||||
location=node)
|
||||
|
||||
def depart_caption(self, node: Element) -> None:
|
||||
if (isinstance(node.parent, nodes.figure) or
|
||||
@ -1271,11 +1271,11 @@ class TexinfoTranslator(SphinxTranslator):
|
||||
|
||||
def unimplemented_visit(self, node: Element) -> None:
|
||||
logger.warning(__("unimplemented node type: %r"), node,
|
||||
location=(self.curfilestack[-1], node.line))
|
||||
location=node)
|
||||
|
||||
def unknown_visit(self, node: Node) -> None:
|
||||
logger.warning(__("unknown node type: %r"), node,
|
||||
location=(self.curfilestack[-1], node.line))
|
||||
location=node)
|
||||
|
||||
def unknown_departure(self, node: Node) -> None:
|
||||
pass
|
||||
|
||||
5
tests/roots/test-domain-c/function_param_target.rst
Normal file
5
tests/roots/test-domain-c/function_param_target.rst
Normal file
@ -0,0 +1,5 @@
|
||||
.. c:function:: void f(int i)
|
||||
|
||||
- :c:var:`i`
|
||||
|
||||
- :c:var:`f.i`
|
||||
25
tests/roots/test-ext-autodoc/target/annotations.py
Normal file
25
tests/roots/test-ext-autodoc/target/annotations.py
Normal file
@ -0,0 +1,25 @@
|
||||
from __future__ import annotations
|
||||
from typing import overload
|
||||
|
||||
|
||||
myint = int
|
||||
|
||||
|
||||
def sum(x: myint, y: myint) -> myint:
|
||||
"""docstring"""
|
||||
return x + y
|
||||
|
||||
|
||||
@overload
|
||||
def mult(x: myint, y: myint) -> myint:
|
||||
...
|
||||
|
||||
|
||||
@overload
|
||||
def mult(x: float, y: float) -> float:
|
||||
...
|
||||
|
||||
|
||||
def mult(x, y):
|
||||
"""docstring"""
|
||||
return x, y
|
||||
7
tests/roots/test-ext-autodoc/target/cached_property.py
Normal file
7
tests/roots/test-ext-autodoc/target/cached_property.py
Normal file
@ -0,0 +1,7 @@
|
||||
from functools import cached_property
|
||||
|
||||
|
||||
class Foo:
|
||||
@cached_property
|
||||
def prop(self) -> int:
|
||||
return 1
|
||||
12
tests/roots/test-ext-autodoc/target/generic_class.py
Normal file
12
tests/roots/test-ext-autodoc/target/generic_class.py
Normal file
@ -0,0 +1,12 @@
|
||||
from typing import TypeVar, Generic
|
||||
|
||||
|
||||
T = TypeVar('T')
|
||||
|
||||
|
||||
# Test that typing.Generic's __new__ method does not mask our class'
|
||||
# __init__ signature.
|
||||
class A(Generic[T]):
|
||||
"""docstring for A"""
|
||||
def __init__(self, a, b=None):
|
||||
pass
|
||||
5
tests/roots/test-ext-autodoc/target/overload2.py
Normal file
5
tests/roots/test-ext-autodoc/target/overload2.py
Normal file
@ -0,0 +1,5 @@
|
||||
from target.overload import Bar
|
||||
|
||||
|
||||
class Baz(Bar):
|
||||
pass
|
||||
@ -2,6 +2,10 @@ class Foo:
|
||||
__slots__ = ['attr']
|
||||
|
||||
|
||||
class FooSingleString:
|
||||
__slots__ = 'attr'
|
||||
|
||||
|
||||
class Bar:
|
||||
__slots__ = {'attr1': 'docstring of attr1',
|
||||
'attr2': 'docstring of attr2',
|
||||
|
||||
2
tests/roots/test-linkcheck-localserver/conf.py
Normal file
2
tests/roots/test-linkcheck-localserver/conf.py
Normal file
@ -0,0 +1,2 @@
|
||||
exclude_patterns = ['_build']
|
||||
linkcheck_anchors = True
|
||||
1
tests/roots/test-linkcheck-localserver/index.rst
Normal file
1
tests/roots/test-linkcheck-localserver/index.rst
Normal file
@ -0,0 +1 @@
|
||||
`local server <http://localhost:7777/#anchor>`_
|
||||
@ -32,8 +32,6 @@ pygments_style = 'sphinx'
|
||||
show_authors = True
|
||||
numfig = True
|
||||
|
||||
rst_epilog = '.. |subst| replace:: global substitution'
|
||||
|
||||
html_sidebars = {'**': ['localtoc.html', 'relations.html', 'sourcelink.html',
|
||||
'customsb.html', 'searchbox.html'],
|
||||
'index': ['contentssb.html', 'localtoc.html', 'globaltoc.html']}
|
||||
|
||||
@ -22,7 +22,9 @@ Meta markup
|
||||
Generic reST
|
||||
------------
|
||||
|
||||
A |subst| (the definition is in rst_epilog).
|
||||
A |subst|!
|
||||
|
||||
.. |subst| replace:: global substitution
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
|
||||
@ -174,3 +174,21 @@ def test_gettext_template_msgid_order_in_sphinxpot(app):
|
||||
'msgid "This is Template 2\\.".*'),
|
||||
result,
|
||||
flags=re.S)
|
||||
|
||||
|
||||
@pytest.mark.sphinx(
|
||||
'gettext', srcdir='root-gettext',
|
||||
confoverrides={'gettext_compact': 'documentation'})
|
||||
def test_build_single_pot(app):
|
||||
app.builder.build_all()
|
||||
|
||||
assert (app.outdir / 'documentation.pot').isfile()
|
||||
|
||||
result = (app.outdir / 'documentation.pot').read_text()
|
||||
assert re.search(
|
||||
('msgid "Todo".*'
|
||||
'msgid "Like footnotes.".*'
|
||||
'msgid "The minute.".*'
|
||||
'msgid "Generated section".*'),
|
||||
result,
|
||||
flags=re.S)
|
||||
|
||||
@ -10,8 +10,10 @@
|
||||
|
||||
import os
|
||||
import re
|
||||
from distutils.version import LooseVersion
|
||||
from itertools import cycle, chain
|
||||
|
||||
import pygments
|
||||
import pytest
|
||||
from html5lib import HTMLParser
|
||||
|
||||
@ -256,7 +258,7 @@ def test_html4_output(app, status, warning):
|
||||
(".//pre/strong", 'try_stmt'),
|
||||
(".//pre/a[@href='#grammar-token-try1_stmt']/code/span", 'try1_stmt'),
|
||||
# tests for ``only`` directive
|
||||
(".//p", 'A global substitution.'),
|
||||
(".//p", 'A global substitution!'),
|
||||
(".//p", 'In HTML.'),
|
||||
(".//p", 'In both.'),
|
||||
(".//p", 'Always present'),
|
||||
@ -419,6 +421,11 @@ def test_html5_output(app, cached_etree_parse, fname, expect):
|
||||
check_xpath(cached_etree_parse(app.outdir / fname), fname, *expect)
|
||||
|
||||
|
||||
@pytest.mark.sphinx('html', parallel=2)
|
||||
def test_html_parallel(app):
|
||||
app.build()
|
||||
|
||||
|
||||
@pytest.mark.skipif(docutils.__version_info__ < (0, 13),
|
||||
reason='docutils-0.13 or above is required')
|
||||
@pytest.mark.sphinx('html')
|
||||
@ -1591,4 +1598,8 @@ def test_html_codeblock_linenos_style_inline(app):
|
||||
app.build()
|
||||
content = (app.outdir / 'index.html').read_text()
|
||||
|
||||
pygments_version = tuple(LooseVersion(pygments.__version__).version)
|
||||
if pygments_version > (2, 7):
|
||||
assert '<span class="linenos">1</span>' in content
|
||||
else:
|
||||
assert '<span class="lineno">1 </span>' in content
|
||||
|
||||
@ -8,8 +8,10 @@
|
||||
:license: BSD, see LICENSE for details.
|
||||
"""
|
||||
|
||||
import http.server
|
||||
import json
|
||||
import re
|
||||
import threading
|
||||
from unittest import mock
|
||||
import pytest
|
||||
|
||||
@ -106,6 +108,21 @@ def test_anchors_ignored(app, status, warning):
|
||||
# expect all ok when excluding #top
|
||||
assert not content
|
||||
|
||||
@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True)
|
||||
def test_raises_for_invalid_status(app, status, warning):
|
||||
server_thread = HttpServerThread(InternalServerErrorHandler, daemon=True)
|
||||
server_thread.start()
|
||||
try:
|
||||
app.builder.build_all()
|
||||
finally:
|
||||
server_thread.terminate()
|
||||
content = (app.outdir / 'output.txt').read_text()
|
||||
assert content == (
|
||||
"index.rst:1: [broken] http://localhost:7777/#anchor: "
|
||||
"500 Server Error: Internal Server Error "
|
||||
"for url: http://localhost:7777/\n"
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.sphinx(
|
||||
'linkcheck', testroot='linkcheck', freshenv=True,
|
||||
@ -160,3 +177,22 @@ def test_linkcheck_request_headers(app, status, warning):
|
||||
assert headers["X-Secret"] == "open sesami"
|
||||
else:
|
||||
assert headers["Accept"] == "text/html,application/xhtml+xml;q=0.9,*/*;q=0.8"
|
||||
|
||||
|
||||
class HttpServerThread(threading.Thread):
|
||||
def __init__(self, handler, *args, **kwargs):
|
||||
super().__init__(*args, **kwargs)
|
||||
self.server = http.server.HTTPServer(("localhost", 7777), handler)
|
||||
|
||||
def run(self):
|
||||
self.server.serve_forever(poll_interval=0.01)
|
||||
|
||||
def terminate(self):
|
||||
self.server.shutdown()
|
||||
self.server.server_close()
|
||||
self.join()
|
||||
|
||||
|
||||
class InternalServerErrorHandler(http.server.BaseHTTPRequestHandler):
|
||||
def do_GET(self):
|
||||
self.send_error(500, "Internal Server Error")
|
||||
|
||||
@ -30,6 +30,13 @@ def test_all(app, status, warning):
|
||||
assert 'Footnotes' not in content
|
||||
|
||||
|
||||
@pytest.mark.sphinx('man', testroot='basic',
|
||||
confoverrides={'man_make_section_directory': True})
|
||||
def test_man_make_section_directory(app, status, warning):
|
||||
app.build()
|
||||
assert (app.outdir / '1' / 'python.1').exists()
|
||||
|
||||
|
||||
@pytest.mark.sphinx('man', testroot='directive-code')
|
||||
def test_captioned_code_block(app, status, warning):
|
||||
app.builder.build_all()
|
||||
|
||||
@ -9,6 +9,8 @@
|
||||
"""
|
||||
import pytest
|
||||
|
||||
from xml.etree import ElementTree
|
||||
|
||||
from sphinx import addnodes
|
||||
from sphinx.addnodes import desc
|
||||
from sphinx.domains.c import DefinitionParser, DefinitionError
|
||||
@ -529,6 +531,25 @@ def filter_warnings(warning, file):
|
||||
return res
|
||||
|
||||
|
||||
def extract_role_links(app, filename):
|
||||
t = (app.outdir / filename).read_text()
|
||||
lis = [l for l in t.split('\n') if l.startswith("<li")]
|
||||
entries = []
|
||||
for l in lis:
|
||||
li = ElementTree.fromstring(l)
|
||||
aList = list(li.iter('a'))
|
||||
assert len(aList) == 1
|
||||
a = aList[0]
|
||||
target = a.attrib['href'].lstrip('#')
|
||||
title = a.attrib['title']
|
||||
assert len(a) == 1
|
||||
code = a[0]
|
||||
assert code.tag == 'code'
|
||||
text = ''.join(code.itertext())
|
||||
entries.append((target, title, text))
|
||||
return entries
|
||||
|
||||
|
||||
@pytest.mark.sphinx(testroot='domain-c', confoverrides={'nitpicky': True})
|
||||
def test_build_domain_c(app, status, warning):
|
||||
app.builder.build_all()
|
||||
@ -562,6 +583,26 @@ def test_build_domain_c_semicolon(app, status, warning):
|
||||
assert len(ws) == 0
|
||||
|
||||
|
||||
@pytest.mark.sphinx(testroot='domain-c', confoverrides={'nitpicky': True})
|
||||
def test_build_function_param_target(app, warning):
|
||||
# the anchor for function parameters should be the function
|
||||
app.builder.build_all()
|
||||
ws = filter_warnings(warning, "function_param_target")
|
||||
assert len(ws) == 0
|
||||
entries = extract_role_links(app, "function_param_target.html")
|
||||
assert entries == [
|
||||
('c.f', 'i', 'i'),
|
||||
('c.f', 'f.i', 'f.i'),
|
||||
]
|
||||
|
||||
|
||||
def _get_obj(app, queryName):
|
||||
domain = app.env.get_domain('c')
|
||||
for name, dispname, objectType, docname, anchor, prio in domain.get_objects():
|
||||
if name == queryName:
|
||||
return (docname, anchor, objectType)
|
||||
return (queryName, "not", "found")
|
||||
|
||||
def test_cfunction(app):
|
||||
text = (".. c:function:: PyObject* "
|
||||
"PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)")
|
||||
@ -569,8 +610,7 @@ def test_cfunction(app):
|
||||
assert_node(doctree[1], addnodes.desc, desctype="function",
|
||||
domain="c", objtype="function", noindex=False)
|
||||
|
||||
domain = app.env.get_domain('c')
|
||||
entry = domain.objects.get('PyType_GenericAlloc')
|
||||
entry = _get_obj(app, 'PyType_GenericAlloc')
|
||||
assert entry == ('index', 'c.PyType_GenericAlloc', 'function')
|
||||
|
||||
|
||||
@ -580,8 +620,7 @@ def test_cmember(app):
|
||||
assert_node(doctree[1], addnodes.desc, desctype="member",
|
||||
domain="c", objtype="member", noindex=False)
|
||||
|
||||
domain = app.env.get_domain('c')
|
||||
entry = domain.objects.get('PyTypeObject.tp_bases')
|
||||
entry = _get_obj(app, 'PyTypeObject.tp_bases')
|
||||
assert entry == ('index', 'c.PyTypeObject.tp_bases', 'member')
|
||||
|
||||
|
||||
@ -591,9 +630,8 @@ def test_cvar(app):
|
||||
assert_node(doctree[1], addnodes.desc, desctype="var",
|
||||
domain="c", objtype="var", noindex=False)
|
||||
|
||||
domain = app.env.get_domain('c')
|
||||
entry = domain.objects.get('PyClass_Type')
|
||||
assert entry == ('index', 'c.PyClass_Type', 'var')
|
||||
entry = _get_obj(app, 'PyClass_Type')
|
||||
assert entry == ('index', 'c.PyClass_Type', 'member')
|
||||
|
||||
|
||||
def test_noindexentry(app):
|
||||
|
||||
@ -1236,3 +1236,18 @@ def test_noindexentry(app):
|
||||
assert_node(doctree, (addnodes.index, desc, addnodes.index, desc))
|
||||
assert_node(doctree[0], addnodes.index, entries=[('single', 'f (C++ function)', '_CPPv41fv', '', None)])
|
||||
assert_node(doctree[2], addnodes.index, entries=[])
|
||||
|
||||
|
||||
def test_mix_decl_duplicate(app, warning):
|
||||
# Issue 8270
|
||||
text = (".. cpp:struct:: A\n"
|
||||
".. cpp:function:: void A()\n"
|
||||
".. cpp:struct:: A\n")
|
||||
restructuredtext.parse(app, text)
|
||||
ws = warning.getvalue().split("\n")
|
||||
assert len(ws) == 5
|
||||
assert "index.rst:2: WARNING: Duplicate C++ declaration, also defined in 'index'." in ws[0]
|
||||
assert "Declaration is 'void A()'." in ws[1]
|
||||
assert "index.rst:3: WARNING: Duplicate C++ declaration, also defined in 'index'." in ws[2]
|
||||
assert "Declaration is 'A'." in ws[3]
|
||||
assert ws[4] == ""
|
||||
@ -313,7 +313,7 @@ def test_pyfunction_signature(app):
|
||||
|
||||
def test_pyfunction_signature_full(app):
|
||||
text = (".. py:function:: hello(a: str, b = 1, *args: str, "
|
||||
"c: bool = True, **kwargs: str) -> str")
|
||||
"c: bool = True, d: tuple = (1, 2), **kwargs: str) -> str")
|
||||
doctree = restructuredtext.parse(app, text)
|
||||
assert_node(doctree, (addnodes.index,
|
||||
[desc, ([desc_signature, ([desc_name, "hello"],
|
||||
@ -343,6 +343,14 @@ def test_pyfunction_signature_full(app):
|
||||
[desc_sig_operator, "="],
|
||||
" ",
|
||||
[nodes.inline, "True"])],
|
||||
[desc_parameter, ([desc_sig_name, "d"],
|
||||
[desc_sig_punctuation, ":"],
|
||||
" ",
|
||||
[desc_sig_name, pending_xref, "tuple"],
|
||||
" ",
|
||||
[desc_sig_operator, "="],
|
||||
" ",
|
||||
[nodes.inline, "(1, 2)"])],
|
||||
[desc_parameter, ([desc_sig_operator, "**"],
|
||||
[desc_sig_name, "kwargs"],
|
||||
[desc_sig_punctuation, ":"],
|
||||
@ -386,6 +394,19 @@ def test_pyfunction_signature_full_py38(app):
|
||||
[desc_parameter, desc_sig_operator, "/"])])
|
||||
|
||||
|
||||
@pytest.mark.skipif(sys.version_info < (3, 8), reason='python 3.8+ is required.')
|
||||
def test_pyfunction_with_number_literals(app):
|
||||
text = ".. py:function:: hello(age=0x10, height=1_6_0)"
|
||||
doctree = restructuredtext.parse(app, text)
|
||||
assert_node(doctree[1][0][1],
|
||||
[desc_parameterlist, ([desc_parameter, ([desc_sig_name, "age"],
|
||||
[desc_sig_operator, "="],
|
||||
[nodes.inline, "0x10"])],
|
||||
[desc_parameter, ([desc_sig_name, "height"],
|
||||
[desc_sig_operator, "="],
|
||||
[nodes.inline, "1_6_0"])])])
|
||||
|
||||
|
||||
def test_optional_pyfunction_signature(app):
|
||||
text = ".. py:function:: compile(source [, filename [, symbol]]) -> ast object"
|
||||
doctree = restructuredtext.parse(app, text)
|
||||
|
||||
@ -290,6 +290,21 @@ def test_format_signature(app):
|
||||
'(b, c=42, *d, **e)'
|
||||
|
||||
|
||||
@pytest.mark.skipif(sys.version_info < (3, 5), reason='typing is available since python3.5.')
|
||||
@pytest.mark.sphinx('html', testroot='ext-autodoc')
|
||||
def test_autodoc_process_signature_typing_generic(app):
|
||||
actual = do_autodoc(app, 'class', 'target.generic_class.A', {})
|
||||
|
||||
assert list(actual) == [
|
||||
'',
|
||||
'.. py:class:: A(a, b=None)',
|
||||
' :module: target.generic_class',
|
||||
'',
|
||||
' docstring for A',
|
||||
'',
|
||||
]
|
||||
|
||||
|
||||
def test_autodoc_process_signature_typehints(app):
|
||||
captured = []
|
||||
|
||||
@ -881,6 +896,26 @@ def test_autodoc_descriptor(app):
|
||||
]
|
||||
|
||||
|
||||
@pytest.mark.skipif(sys.version_info < (3, 8),
|
||||
reason='cached_property is available since python3.8.')
|
||||
@pytest.mark.sphinx('html', testroot='ext-autodoc')
|
||||
def test_autodoc_cached_property(app):
|
||||
options = {"members": None,
|
||||
"undoc-members": True}
|
||||
actual = do_autodoc(app, 'class', 'target.cached_property.Foo', options)
|
||||
assert list(actual) == [
|
||||
'',
|
||||
'.. py:class:: Foo()',
|
||||
' :module: target.cached_property',
|
||||
'',
|
||||
'',
|
||||
' .. py:method:: Foo.prop',
|
||||
' :module: target.cached_property',
|
||||
' :property:',
|
||||
'',
|
||||
]
|
||||
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='ext-autodoc')
|
||||
def test_autodoc_member_order(app):
|
||||
# case member-order='bysource'
|
||||
@ -1170,6 +1205,14 @@ def test_slots(app):
|
||||
' .. py:attribute:: Foo.attr',
|
||||
' :module: target.slots',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: FooSingleString()',
|
||||
' :module: target.slots',
|
||||
'',
|
||||
'',
|
||||
' .. py:attribute:: FooSingleString.attr',
|
||||
' :module: target.slots',
|
||||
'',
|
||||
]
|
||||
|
||||
|
||||
@ -1967,6 +2010,22 @@ def test_overload(app):
|
||||
]
|
||||
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='ext-autodoc')
|
||||
def test_overload2(app):
|
||||
options = {"members": None}
|
||||
actual = do_autodoc(app, 'module', 'target.overload2', options)
|
||||
assert list(actual) == [
|
||||
'',
|
||||
'.. py:module:: target.overload2',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: Baz(x: int, y: int)',
|
||||
' Baz(x: str, y: str)',
|
||||
' :module: target.overload2',
|
||||
'',
|
||||
]
|
||||
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='ext-autodoc')
|
||||
def test_pymodule_for_ModuleLevelDocumenter(app):
|
||||
app.env.ref_context['py:module'] = 'target.classes'
|
||||
|
||||
@ -610,6 +610,54 @@ def test_autodoc_typehints_none(app):
|
||||
]
|
||||
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='ext-autodoc',
|
||||
confoverrides={'autodoc_typehints': 'none'})
|
||||
def test_autodoc_typehints_none_for_overload(app):
|
||||
options = {"members": None}
|
||||
actual = do_autodoc(app, 'module', 'target.overload', options)
|
||||
assert list(actual) == [
|
||||
'',
|
||||
'.. py:module:: target.overload',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: Bar(x, y)',
|
||||
' :module: target.overload',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: Baz(x, y)',
|
||||
' :module: target.overload',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: Foo(x, y)',
|
||||
' :module: target.overload',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: Math()',
|
||||
' :module: target.overload',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
' .. py:method:: Math.sum(x, y)',
|
||||
' :module: target.overload',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:function:: sum(x, y)',
|
||||
' :module: target.overload',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
]
|
||||
|
||||
|
||||
@pytest.mark.sphinx('text', testroot='ext-autodoc',
|
||||
confoverrides={'autodoc_typehints': "description"})
|
||||
def test_autodoc_typehints_description(app):
|
||||
@ -642,6 +690,54 @@ def test_autodoc_typehints_description_for_invalid_node(app):
|
||||
restructuredtext.parse(app, text) # raises no error
|
||||
|
||||
|
||||
@pytest.mark.skipif(sys.version_info < (3, 7), reason='python 3.7+ is required.')
|
||||
@pytest.mark.sphinx('text', testroot='ext-autodoc')
|
||||
def test_autodoc_type_aliases(app):
|
||||
# default
|
||||
options = {"members": None}
|
||||
actual = do_autodoc(app, 'module', 'target.annotations', options)
|
||||
assert list(actual) == [
|
||||
'',
|
||||
'.. py:module:: target.annotations',
|
||||
'',
|
||||
'',
|
||||
'.. py:function:: mult(x: int, y: int) -> int',
|
||||
' mult(x: float, y: float) -> float',
|
||||
' :module: target.annotations',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:function:: sum(x: int, y: int) -> int',
|
||||
' :module: target.annotations',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
]
|
||||
|
||||
# define aliases
|
||||
app.config.autodoc_type_aliases = {'myint': 'myint'}
|
||||
actual = do_autodoc(app, 'module', 'target.annotations', options)
|
||||
assert list(actual) == [
|
||||
'',
|
||||
'.. py:module:: target.annotations',
|
||||
'',
|
||||
'',
|
||||
'.. py:function:: mult(x: myint, y: myint) -> myint',
|
||||
' mult(x: float, y: float) -> float',
|
||||
' :module: target.annotations',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:function:: sum(x: myint, y: myint) -> myint',
|
||||
' :module: target.annotations',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
]
|
||||
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='ext-autodoc')
|
||||
def test_autodoc_default_options(app):
|
||||
# no settings
|
||||
|
||||
@ -28,7 +28,8 @@ def test_process_docstring(app):
|
||||
'.. py:function:: func()',
|
||||
' :module: target.process_docstring',
|
||||
'',
|
||||
' my docstring'
|
||||
' my docstring',
|
||||
'',
|
||||
]
|
||||
|
||||
|
||||
|
||||
@ -1177,7 +1177,7 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:returns: *str* -- Extended
|
||||
:returns: :class:`str` -- Extended
|
||||
description of return value
|
||||
"""
|
||||
), (
|
||||
@ -1193,7 +1193,7 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:returns: *str* -- Extended
|
||||
:returns: :class:`str` -- Extended
|
||||
description of return value
|
||||
"""
|
||||
), (
|
||||
@ -1246,7 +1246,7 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Yields: *str* -- Extended
|
||||
:Yields: :class:`str` -- Extended
|
||||
description of yielded value
|
||||
"""
|
||||
), (
|
||||
@ -1262,7 +1262,7 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Yields: *str* -- Extended
|
||||
:Yields: :class:`str` -- Extended
|
||||
description of yielded value
|
||||
"""
|
||||
)]
|
||||
@ -1455,9 +1455,38 @@ numpy.multivariate_normal(mean, cov, shape=None, spam=None)
|
||||
|
||||
.. seealso::
|
||||
|
||||
:meth:`some`, :meth:`other`, :meth:`funcs`
|
||||
:obj:`some`, :obj:`other`, :obj:`funcs`
|
||||
\n\
|
||||
:meth:`otherfunc`
|
||||
:obj:`otherfunc`
|
||||
relationship
|
||||
"""
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
docstring = """\
|
||||
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
|
||||
|
||||
See Also
|
||||
--------
|
||||
some, other, :func:`funcs`
|
||||
otherfunc : relationship
|
||||
|
||||
"""
|
||||
translations = {
|
||||
"other": "MyClass.other",
|
||||
"otherfunc": ":func:`~my_package.otherfunc`",
|
||||
}
|
||||
config = Config(napoleon_type_aliases=translations)
|
||||
app = mock.Mock()
|
||||
actual = str(NumpyDocstring(docstring, config, app, "method"))
|
||||
|
||||
expected = """\
|
||||
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
|
||||
|
||||
.. seealso::
|
||||
|
||||
:obj:`some`, :obj:`MyClass.other`, :func:`funcs`
|
||||
\n\
|
||||
:func:`~my_package.otherfunc`
|
||||
relationship
|
||||
"""
|
||||
self.assertEqual(expected, actual)
|
||||
@ -1526,6 +1555,52 @@ arg_ : type
|
||||
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
def test_return_types(self):
|
||||
docstring = dedent("""
|
||||
Returns
|
||||
-------
|
||||
DataFrame
|
||||
a dataframe
|
||||
""")
|
||||
expected = dedent("""
|
||||
:returns: a dataframe
|
||||
:rtype: :class:`~pandas.DataFrame`
|
||||
""")
|
||||
translations = {
|
||||
"DataFrame": "~pandas.DataFrame",
|
||||
}
|
||||
config = Config(
|
||||
napoleon_use_param=True,
|
||||
napoleon_use_rtype=True,
|
||||
napoleon_preprocess_types=True,
|
||||
napoleon_type_aliases=translations,
|
||||
)
|
||||
actual = str(NumpyDocstring(docstring, config))
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
def test_yield_types(self):
|
||||
docstring = dedent("""
|
||||
Example Function
|
||||
|
||||
Yields
|
||||
------
|
||||
scalar or array-like
|
||||
The result of the computation
|
||||
""")
|
||||
expected = dedent("""
|
||||
Example Function
|
||||
|
||||
:Yields: :term:`scalar` or :class:`array-like <numpy.ndarray>` -- The result of the computation
|
||||
""")
|
||||
translations = {
|
||||
"scalar": ":term:`scalar`",
|
||||
"array-like": ":class:`array-like <numpy.ndarray>`",
|
||||
}
|
||||
config = Config(napoleon_type_aliases=translations, napoleon_preprocess_types=True)
|
||||
app = mock.Mock()
|
||||
actual = str(NumpyDocstring(docstring, config, app, "method"))
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
def test_raises_types(self):
|
||||
docstrings = [("""
|
||||
Example Function
|
||||
@ -1690,6 +1765,34 @@ Example Function
|
||||
("""
|
||||
Example Function
|
||||
|
||||
Raises
|
||||
------
|
||||
CustomError
|
||||
If the dimensions couldn't be parsed.
|
||||
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises package.CustomError: If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
Example Function
|
||||
|
||||
Raises
|
||||
------
|
||||
AnotherError
|
||||
If the dimensions couldn't be parsed.
|
||||
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises ~package.AnotherError: If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
Example Function
|
||||
|
||||
Raises
|
||||
------
|
||||
:class:`exc.InvalidDimensionsError`
|
||||
@ -1702,7 +1805,11 @@ Example Function
|
||||
:raises exc.InvalidArgumentsError:
|
||||
""")]
|
||||
for docstring, expected in docstrings:
|
||||
config = Config()
|
||||
translations = {
|
||||
"CustomError": "package.CustomError",
|
||||
"AnotherError": ":py:exc:`~package.AnotherError`",
|
||||
}
|
||||
config = Config(napoleon_type_aliases=translations, napoleon_preprocess_types=True)
|
||||
app = mock.Mock()
|
||||
actual = str(NumpyDocstring(docstring, config, app, "method"))
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
@ -14,8 +14,10 @@ import re
|
||||
|
||||
import pytest
|
||||
from babel.messages import pofile, mofile
|
||||
from babel.messages.catalog import Catalog
|
||||
from docutils import nodes
|
||||
|
||||
from sphinx import locale
|
||||
from sphinx.testing.util import (
|
||||
path, etree_parse, strip_escseq,
|
||||
assert_re_search, assert_not_re_search, assert_startswith, assert_node
|
||||
@ -1289,3 +1291,30 @@ def test_image_glob_intl_using_figure_language_filename(app):
|
||||
|
||||
def getwarning(warnings):
|
||||
return strip_escseq(warnings.getvalue().replace(os.sep, '/'))
|
||||
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='basic', confoverrides={'language': 'de'})
|
||||
def test_customize_system_message(make_app, app_params, sphinx_test_tempdir):
|
||||
try:
|
||||
# clear translators cache
|
||||
locale.translators.clear()
|
||||
|
||||
# prepare message catalog (.po)
|
||||
locale_dir = sphinx_test_tempdir / 'basic' / 'locales' / 'de' / 'LC_MESSAGES'
|
||||
locale_dir.makedirs()
|
||||
with (locale_dir / 'sphinx.po').open('wb') as f:
|
||||
catalog = Catalog()
|
||||
catalog.add('Quick search', 'QUICK SEARCH')
|
||||
pofile.write_po(f, catalog)
|
||||
|
||||
# construct application and convert po file to .mo
|
||||
args, kwargs = app_params
|
||||
app = make_app(*args, **kwargs)
|
||||
assert (locale_dir / 'sphinx.mo').exists()
|
||||
assert app.translator.gettext('Quick search') == 'QUICK SEARCH'
|
||||
|
||||
app.build()
|
||||
content = (app.outdir / 'index.html').read_text()
|
||||
assert 'QUICK SEARCH' in content
|
||||
finally:
|
||||
locale.translators.clear()
|
||||
|
||||
@ -53,12 +53,12 @@ from sphinx.pycode import ast
|
||||
("+ a", "+ a"), # UAdd
|
||||
("- 1", "- 1"), # UnaryOp
|
||||
("- a", "- a"), # USub
|
||||
("(1, 2, 3)", "1, 2, 3"), # Tuple
|
||||
("(1, 2, 3)", "(1, 2, 3)"), # Tuple
|
||||
("()", "()"), # Tuple (empty)
|
||||
])
|
||||
def test_unparse(source, expected):
|
||||
module = ast.parse(source)
|
||||
assert ast.unparse(module.body[0].value) == expected
|
||||
assert ast.unparse(module.body[0].value, source) == expected
|
||||
|
||||
|
||||
def test_unparse_None():
|
||||
@ -66,8 +66,12 @@ def test_unparse_None():
|
||||
|
||||
|
||||
@pytest.mark.skipif(sys.version_info < (3, 8), reason='python 3.8+ is required.')
|
||||
def test_unparse_py38():
|
||||
source = "lambda x=0, /, y=1, *args, z, **kwargs: x + y + z"
|
||||
expected = "lambda x=0, /, y=1, *args, z, **kwargs: ..."
|
||||
@pytest.mark.parametrize('source,expected', [
|
||||
("lambda x=0, /, y=1, *args, z, **kwargs: x + y + z",
|
||||
"lambda x=0, /, y=1, *args, z, **kwargs: ..."), # posonlyargs
|
||||
("0x1234", "0x1234"), # Constant
|
||||
("1_000_000", "1_000_000"), # Constant
|
||||
])
|
||||
def test_unparse_py38(source, expected):
|
||||
module = ast.parse(source)
|
||||
assert ast.unparse(module.body[0].value) == expected
|
||||
assert ast.unparse(module.body[0].value, source) == expected
|
||||
|
||||
@ -32,6 +32,10 @@ class MyList(List[T]):
|
||||
pass
|
||||
|
||||
|
||||
class BrokenType:
|
||||
__args__ = int
|
||||
|
||||
|
||||
def test_stringify():
|
||||
assert stringify(int) == "int"
|
||||
assert stringify(str) == "str"
|
||||
@ -113,3 +117,7 @@ def test_stringify_type_hints_alias():
|
||||
MyTuple = Tuple[str, str]
|
||||
assert stringify(MyStr) == "str"
|
||||
assert stringify(MyTuple) == "Tuple[str, str]" # type: ignore
|
||||
|
||||
|
||||
def test_stringify_broken_type_hints():
|
||||
assert stringify(BrokenType) == 'test_util_typing.BrokenType'
|
||||
|
||||
11
tox.ini
11
tox.ini
@ -26,6 +26,7 @@ extras =
|
||||
test
|
||||
setenv =
|
||||
PYTHONWARNINGS = all,ignore::ImportWarning:importlib._bootstrap_external,ignore::DeprecationWarning:site,ignore::DeprecationWarning:distutils
|
||||
PYTEST_ADDOPTS = --color yes
|
||||
commands=
|
||||
pytest --durations 25 {posargs}
|
||||
|
||||
@ -40,16 +41,6 @@ extras =
|
||||
commands =
|
||||
flake8 {posargs}
|
||||
|
||||
[testenv:pylint]
|
||||
basepython = python3
|
||||
description =
|
||||
Run source code analyzer.
|
||||
deps =
|
||||
pylint
|
||||
{[testenv]deps}
|
||||
commands =
|
||||
pylint --rcfile utils/pylintrc sphinx
|
||||
|
||||
[testenv:coverage]
|
||||
basepython = python3
|
||||
description =
|
||||
|
||||
301
utils/pylintrc
301
utils/pylintrc
@ -1,301 +0,0 @@
|
||||
# lint Python modules using external checkers.
|
||||
#
|
||||
# This is the main checker controlling the other ones and the reports
|
||||
# generation. It is itself both a raw checker and an astng checker in order
|
||||
# to:
|
||||
# * handle message activation / deactivation at the module level
|
||||
# * handle some basic but necessary stats'data (number of classes, methods...)
|
||||
#
|
||||
[MASTER]
|
||||
|
||||
# Specify a configuration file.
|
||||
#rcfile=
|
||||
|
||||
# Profiled execution.
|
||||
profile=no
|
||||
|
||||
# Add <file or directory> to the black list. It should be a base name, not a
|
||||
# path. You may set this option multiple times.
|
||||
ignore=.svn
|
||||
|
||||
# Pickle collected data for later comparisons.
|
||||
persistent=yes
|
||||
|
||||
# Set the cache size for astng objects.
|
||||
cache-size=500
|
||||
|
||||
# List of plugins (as comma separated values of python modules names) to load,
|
||||
# usually to register additional checkers.
|
||||
load-plugins=
|
||||
|
||||
|
||||
[MESSAGES CONTROL]
|
||||
|
||||
# Enable only checker(s) with the given id(s). This option conflict with the
|
||||
# disable-checker option
|
||||
#enable-checker=
|
||||
|
||||
# Enable all checker(s) except those with the given id(s). This option conflict
|
||||
# with the disable-checker option
|
||||
#disable-checker=
|
||||
|
||||
# Enable all messages in the listed categories.
|
||||
#enable-msg-cat=
|
||||
|
||||
# Disable all messages in the listed categories.
|
||||
#disable-msg-cat=
|
||||
|
||||
# Enable the message(s) with the given id(s).
|
||||
#enable-msg=
|
||||
|
||||
# Disable the message(s) with the given id(s).
|
||||
disable-msg=C0323,W0142,C0301,C0103,C0111,E0213,C0302,C0203,W0703,R0201,W0613,W0612,W0622
|
||||
|
||||
|
||||
[REPORTS]
|
||||
|
||||
# set the output format. Available formats are text, parseable, colorized and
|
||||
# html
|
||||
output-format=colorized
|
||||
|
||||
# Include message's id in output
|
||||
include-ids=yes
|
||||
|
||||
# Put messages in a separate file for each module / package specified on the
|
||||
# command line instead of printing them on stdout. Reports (if any) will be
|
||||
# written in a file name "pylint_global.[txt|html]".
|
||||
files-output=no
|
||||
|
||||
# Tells wether to display a full report or only the messages
|
||||
reports=yes
|
||||
|
||||
# Python expression which should return a note less than 10 (10 is the highest
|
||||
# note).You have access to the variables errors warning, statement which
|
||||
# respectively contain the number of errors / warnings messages and the total
|
||||
# number of statements analyzed. This is used by the global evaluation report
|
||||
# (R0004).
|
||||
evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
|
||||
|
||||
# Add a comment according to your evaluation note. This is used by the global
|
||||
# evaluation report (R0004).
|
||||
comment=no
|
||||
|
||||
# Enable the report(s) with the given id(s).
|
||||
#enable-report=
|
||||
|
||||
# Disable the report(s) with the given id(s).
|
||||
#disable-report=
|
||||
|
||||
|
||||
# checks for
|
||||
# * unused variables / imports
|
||||
# * undefined variables
|
||||
# * redefinition of variable from builtins or from an outer scope
|
||||
# * use of variable before assigment
|
||||
#
|
||||
[VARIABLES]
|
||||
|
||||
# Tells wether we should check for unused import in __init__ files.
|
||||
init-import=no
|
||||
|
||||
# A regular expression matching names used for dummy variables (i.e. not used).
|
||||
dummy-variables-rgx=_|dummy
|
||||
|
||||
# List of additional names supposed to be defined in builtins. Remember that
|
||||
# you should avoid to define new builtins when possible.
|
||||
additional-builtins=
|
||||
|
||||
|
||||
# try to find bugs in the code using type inference
|
||||
#
|
||||
[TYPECHECK]
|
||||
|
||||
# Tells wether missing members accessed in mixin class should be ignored. A
|
||||
# mixin class is detected if its name ends with "mixin" (case insensitive).
|
||||
ignore-mixin-members=yes
|
||||
|
||||
# When zope mode is activated, consider the acquired-members option to ignore
|
||||
# access to some undefined attributes.
|
||||
zope=no
|
||||
|
||||
# List of members which are usually get through zope's acquisition mecanism and
|
||||
# so shouldn't trigger E0201 when accessed (need zope=yes to be considered).
|
||||
acquired-members=REQUEST,acl_users,aq_parent
|
||||
|
||||
|
||||
# checks for :
|
||||
# * doc strings
|
||||
# * modules / classes / functions / methods / arguments / variables name
|
||||
# * number of arguments, local variables, branchs, returns and statements in
|
||||
# functions, methods
|
||||
# * required module attributes
|
||||
# * dangerous default values as arguments
|
||||
# * redefinition of function / method / class
|
||||
# * uses of the global statement
|
||||
#
|
||||
[BASIC]
|
||||
|
||||
# Required attributes for module, separated by a comma
|
||||
required-attributes=
|
||||
|
||||
# Regular expression which should only match functions or classes name which do
|
||||
# not require a docstring
|
||||
no-docstring-rgx=__.*__
|
||||
|
||||
# Regular expression which should only match correct module names
|
||||
module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
|
||||
|
||||
# Regular expression which should only match correct module level names
|
||||
const-rgx=(([A-Z_][A-Z1-9_]*)|(__.*__))$
|
||||
|
||||
# Regular expression which should only match correct class names
|
||||
class-rgx=[A-Z_][a-zA-Z0-9]+$
|
||||
|
||||
# Regular expression which should only match correct function names
|
||||
function-rgx=[a-z_][a-z0-9_]{2,30}$
|
||||
|
||||
# Regular expression which should only match correct method names
|
||||
method-rgx=[a-z_][a-z0-9_]{2,30}$
|
||||
|
||||
# Regular expression which should only match correct instance attribute names
|
||||
attr-rgx=[a-z_][a-z0-9_]{2,30}$
|
||||
|
||||
# Regular expression which should only match correct argument names
|
||||
argument-rgx=[a-z_][a-z0-9_]{2,30}$
|
||||
|
||||
# Regular expression which should only match correct variable names
|
||||
variable-rgx=[a-z_][a-z0-9_]{2,30}$
|
||||
|
||||
# Regular expression which should only match correct list comprehension /
|
||||
# generator expression variable names
|
||||
inlinevar-rgx=[A-Za-z_][A-Za-z0-9_]*$
|
||||
|
||||
# Good variable names which should always be accepted, separated by a comma
|
||||
good-names=i,j,k,ex,Run,_
|
||||
|
||||
# Bad variable names which should always be refused, separated by a comma
|
||||
bad-names=foo,bar,baz,toto,tutu,tata
|
||||
|
||||
# List of builtins function names that should not be used, separated by a comma
|
||||
bad-functions=apply,input
|
||||
|
||||
|
||||
# checks for sign of poor/misdesign:
|
||||
# * number of methods, attributes, local variables...
|
||||
# * size, complexity of functions, methods
|
||||
#
|
||||
[DESIGN]
|
||||
|
||||
# Maximum number of arguments for function / method
|
||||
max-args=12
|
||||
|
||||
# Maximum number of locals for function / method body
|
||||
max-locals=30
|
||||
|
||||
# Maximum number of return / yield for function / method body
|
||||
max-returns=12
|
||||
|
||||
# Maximum number of branch for function / method body
|
||||
max-branchs=30
|
||||
|
||||
# Maximum number of statements in function / method body
|
||||
max-statements=60
|
||||
|
||||
# Maximum number of parents for a class (see R0901).
|
||||
max-parents=7
|
||||
|
||||
# Maximum number of attributes for a class (see R0902).
|
||||
max-attributes=20
|
||||
|
||||
# Minimum number of public methods for a class (see R0903).
|
||||
min-public-methods=0
|
||||
|
||||
# Maximum number of public methods for a class (see R0904).
|
||||
max-public-methods=20
|
||||
|
||||
|
||||
# checks for
|
||||
# * external modules dependencies
|
||||
# * relative / wildcard imports
|
||||
# * cyclic imports
|
||||
# * uses of deprecated modules
|
||||
#
|
||||
[IMPORTS]
|
||||
|
||||
# Deprecated modules which should not be used, separated by a comma
|
||||
deprecated-modules=regsub,string,TERMIOS,Bastion,rexec
|
||||
|
||||
# Create a graph of every (i.e. internal and external) dependencies in the
|
||||
# given file (report R0402 must not be disabled)
|
||||
import-graph=
|
||||
|
||||
# Create a graph of external dependencies in the given file (report R0402 must
|
||||
# not be disabled)
|
||||
ext-import-graph=
|
||||
|
||||
# Create a graph of internal dependencies in the given file (report R0402 must
|
||||
# not be disabled)
|
||||
int-import-graph=
|
||||
|
||||
|
||||
# checks for :
|
||||
# * methods without self as first argument
|
||||
# * overridden methods signature
|
||||
# * access only to existant members via self
|
||||
# * attributes not defined in the __init__ method
|
||||
# * supported interfaces implementation
|
||||
# * unreachable code
|
||||
#
|
||||
[CLASSES]
|
||||
|
||||
# List of interface methods to ignore, separated by a comma. This is used for
|
||||
# instance to not check methods defines in Zope's Interface base class.
|
||||
ignore-iface-methods=isImplementedBy,deferred,extends,names,namesAndDescriptions,queryDescriptionFor,getBases,getDescriptionFor,getDoc,getName,getTaggedValue,getTaggedValueTags,isEqualOrExtendedBy,setTaggedValue,isImplementedByInstancesOf,adaptWith,is_implemented_by
|
||||
|
||||
# List of method names used to declare (i.e. assign) instance attributes.
|
||||
defining-attr-methods=__init__,__new__,setUp
|
||||
|
||||
|
||||
# checks for similarities and duplicated code. This computation may be
|
||||
# memory / CPU intensive, so you should disable it if you experiments some
|
||||
# problems.
|
||||
#
|
||||
[SIMILARITIES]
|
||||
|
||||
# Minimum lines number of a similarity.
|
||||
min-similarity-lines=10
|
||||
|
||||
# Ignore comments when computing similarities.
|
||||
ignore-comments=yes
|
||||
|
||||
# Ignore docstrings when computing similarities.
|
||||
ignore-docstrings=yes
|
||||
|
||||
|
||||
# checks for:
|
||||
# * warning notes in the code
|
||||
# * PEP 263: source code with non ascii character but no encoding declaration
|
||||
#
|
||||
[MISCELLANEOUS]
|
||||
|
||||
# List of note tags to take in consideration, separated by a comma.
|
||||
notes=FIXME,XXX,TODO
|
||||
|
||||
|
||||
# checks for :
|
||||
# * unauthorized constructions
|
||||
# * strict indentation
|
||||
# * line length
|
||||
# * use of <> instead of !=
|
||||
#
|
||||
[FORMAT]
|
||||
|
||||
# Maximum number of characters on a single line.
|
||||
max-line-length=90
|
||||
|
||||
# Maximum number of lines in a module
|
||||
max-module-lines=1000
|
||||
|
||||
# String used as indentation unit. This is usually " " (4 spaces) or "\t" (1
|
||||
# tab).
|
||||
indent-string=' '
|
||||
Loading…
Reference in New Issue
Block a user