mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2026-10-13 17:02:12 -05:00
Merge branch '3.x' into 4422_support_GenericAlias
This commit is contained in:
15 files changed
+874
-704
No files matched your search
@@ -49,6 +49,7 @@ Features added
|
||||
* #7143: autodoc: Support final classes and methods
|
||||
* #7384: autodoc: Support signatures defined by ``__new__()``, metaclasses and
|
||||
builtin base classes
|
||||
* #2106: autodoc: Support multiple signatures on docstring
|
||||
* #4422: autodoc: Support GenericAlias in Python 3.7 or above
|
||||
* #7466: autosummary: headings in generated documents are not translated
|
||||
* #7490: autosummary: Add ``:caption:`` option to autosummary directive to set a
|
||||
|
||||
+3
-16
@@ -1,4 +1,3 @@
|
||||
|
||||
.. _contents:
|
||||
|
||||
Sphinx documentation contents
|
||||
@@ -7,26 +6,14 @@ Sphinx documentation contents
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
intro
|
||||
|
||||
usage/installation
|
||||
usage/quickstart
|
||||
usage/restructuredtext/index
|
||||
usage/markdown
|
||||
usage/configuration
|
||||
usage/builders/index
|
||||
usage/extensions/index
|
||||
usage/theming
|
||||
usage/advanced/intl
|
||||
usage/advanced/setuptools
|
||||
usage/advanced/websupport/index
|
||||
|
||||
usage/index
|
||||
development/index
|
||||
man/index
|
||||
|
||||
theming
|
||||
templating
|
||||
latex
|
||||
extdev/index
|
||||
development/tutorials/index
|
||||
|
||||
faq
|
||||
glossary
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
================
|
||||
Extending Sphinx
|
||||
================
|
||||
|
||||
This guide is aimed at those wishing to develop their own extensions for
|
||||
Sphinx. Sphinx possesses significant extensibility capabilities including the
|
||||
ability to hook into almost every point of the build process. If you simply
|
||||
wish to use Sphinx with existing extensions, refer to :doc:`/usage/index`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
tutorials/index
|
||||
+37
@@ -148,6 +148,43 @@ Google Search
|
||||
.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
|
||||
|
||||
|
||||
Sphinx vs. Docutils
|
||||
-------------------
|
||||
|
||||
tl;dr: *docutils* converts reStructuredText to multiple output formats. Sphinx
|
||||
builds upon docutils to allow construction of cross-referenced and indexed
|
||||
bodies of documentation.
|
||||
|
||||
`docutils`__ is a text processing system for converting plain text
|
||||
documentation into other, richer formats. As noted in the `docutils
|
||||
documentation`__, docutils uses *readers* to read a document, *parsers* for
|
||||
parsing plain text formats into an internal tree representation made up of
|
||||
different types of *nodes*, and *writers* to output this tree in various
|
||||
document formats. docutils provides parsers for one plain text format -
|
||||
`reStructuredText`__ - though other, *out-of-tree* parsers have been
|
||||
implemented including Sphinx's :doc:`Markdown parser </usage/markdown>`. On the
|
||||
other hand, it provides writers for many different formats including HTML,
|
||||
LaTeX, man pages, Open Document Format and XML.
|
||||
|
||||
docutils exposes all of its functionality through a variety of `front-end
|
||||
tools`__, such as ``rst2html``, ``rst2odt`` and ``rst2xml``. Crucially though,
|
||||
all of these tools, and docutils itself, are concerned with individual
|
||||
documents. They don't support concepts such as cross-referencing, indexing of
|
||||
documents, or the construction of a document hierarchy (typically manifesting
|
||||
in a table of contents).
|
||||
|
||||
Sphinx builds upon docutils by harnessing docutils' readers and parsers and
|
||||
providing its own :doc:`/usage/builders/index`. As a result, Sphinx wraps some
|
||||
of the *writers* provided by docutils. This allows Sphinx to provide many
|
||||
features that would simply not be possible with docutils, such as those
|
||||
outlined above.
|
||||
|
||||
__ http://docutils.sourceforge.io/
|
||||
__ http://docutils.sourceforge.io/docs/dev/hacking.html
|
||||
__ http://docutils.sourceforge.io/rst.html
|
||||
__ http://docutils.sourceforge.net/docs/user/tools.html
|
||||
|
||||
|
||||
.. _epub-faq:
|
||||
|
||||
Epub info
|
||||
|
||||
@@ -1,71 +0,0 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
This is the documentation for the Sphinx documentation builder. Sphinx is a
|
||||
tool that translates a set of reStructuredText_ source files into various output
|
||||
formats, automatically producing cross-references, indices, etc. That is, if
|
||||
you have a directory containing a bunch of reST-formatted documents (and
|
||||
possibly subdirectories of docs in there as well), Sphinx can generate a
|
||||
nicely-organized arrangement of HTML files (in some other directory) for easy
|
||||
browsing and navigation. But from the same source, it can also generate a PDF
|
||||
file using LaTeX.
|
||||
|
||||
The focus is on hand-written documentation, rather than auto-generated API docs.
|
||||
Though there is support for that kind of documentation as well (which is
|
||||
intended to be freely mixed with hand-written content), if you need pure API
|
||||
docs have a look at `Epydoc <http://epydoc.sourceforge.net/>`_, which also
|
||||
understands reST.
|
||||
|
||||
For a great "introduction" to writing docs in general -- the whys and hows, see
|
||||
also `Write the docs`_, written by Eric Holscher.
|
||||
|
||||
.. _rinohtype: https://github.com/brechtm/rinohtype
|
||||
.. _Write the docs: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
|
||||
|
||||
Conversion from other systems
|
||||
-----------------------------
|
||||
|
||||
This section is intended to collect helpful hints for those wanting to migrate
|
||||
to reStructuredText/Sphinx from other documentation systems.
|
||||
|
||||
* Gerard Flanagan has written a script to convert pure HTML to reST; it can be
|
||||
found at the `Python Package Index <https://pypi.org/project/html2rest/>`_.
|
||||
|
||||
* For converting the old Python docs to Sphinx, a converter was written which
|
||||
can be found at `the Python SVN repository
|
||||
<https://svn.python.org/projects/doctools/converter/>`_. It contains generic
|
||||
code to convert Python-doc-style LaTeX markup to Sphinx reST.
|
||||
|
||||
* Marcin Wojdyr has written a script to convert Docbook to reST with Sphinx
|
||||
markup; it is at `GitHub <https://github.com/wojdyr/db2rst>`_.
|
||||
|
||||
* Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents
|
||||
to Sphinx: `odt2sphinx <https://pypi.org/project/odt2sphinx/>`_.
|
||||
|
||||
* To convert different markups, `Pandoc <https://pandoc.org/>`_ is
|
||||
a very helpful tool.
|
||||
|
||||
|
||||
Use with other systems
|
||||
----------------------
|
||||
|
||||
See the :ref:`pertinent section in the FAQ list <usingwith>`.
|
||||
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Sphinx needs at least **Python 3.5** to run.
|
||||
It also depends on 3rd party libraries such as docutils_ and jinja2_, but they
|
||||
are automatically installed when sphinx is installed.
|
||||
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
.. _docutils: http://docutils.sourceforge.net/
|
||||
.. _Jinja2: http://jinja.pocoo.org/
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
See :doc:`/usage/quickstart` for an introduction. It also contains links to
|
||||
more advanced sections in this manual for the topics it discusses.
|
||||
+628
-533
File diff suppressed because it is too large.
Load diff
+45
-43
@@ -2,6 +2,7 @@
|
||||
|
||||
.. _templating:
|
||||
|
||||
==========
|
||||
Templating
|
||||
==========
|
||||
|
||||
@@ -69,9 +70,10 @@ following contents::
|
||||
By prefixing the name of the overridden template with an exclamation mark,
|
||||
Sphinx will load the layout template from the underlying HTML theme.
|
||||
|
||||
**Important**: If you override a block, call ``{{ super() }}`` somewhere to
|
||||
render the block's original content in the extended template -- unless you
|
||||
don't want that content to show up.
|
||||
.. important::
|
||||
If you override a block, call ``{{ super() }}`` somewhere to render the
|
||||
block's original content in the extended template -- unless you don't want
|
||||
that content to show up.
|
||||
|
||||
|
||||
Working with the builtin templates
|
||||
@@ -85,72 +87,68 @@ Blocks
|
||||
|
||||
The following blocks exist in the ``layout.html`` template:
|
||||
|
||||
`doctype`
|
||||
``doctype``
|
||||
The doctype of the output format. By default this is XHTML 1.0 Transitional
|
||||
as this is the closest to what Sphinx and Docutils generate and it's a good
|
||||
idea not to change it unless you want to switch to HTML 5 or a different but
|
||||
compatible XHTML doctype.
|
||||
|
||||
`linktags`
|
||||
``linktags``
|
||||
This block adds a couple of ``<link>`` tags to the head section of the
|
||||
template.
|
||||
|
||||
`extrahead`
|
||||
``extrahead``
|
||||
This block is empty by default and can be used to add extra contents into
|
||||
the ``<head>`` tag of the generated HTML file. This is the right place to
|
||||
add references to JavaScript or extra CSS files.
|
||||
|
||||
`relbar1` / `relbar2`
|
||||
``relbar1``, ``relbar2``
|
||||
This block contains the *relation bar*, the list of related links (the
|
||||
parent documents on the left, and the links to index, modules etc. on the
|
||||
right). `relbar1` appears before the document, `relbar2` after the
|
||||
right). ``relbar1`` appears before the document, ``relbar2`` after the
|
||||
document. By default, both blocks are filled; to show the relbar only
|
||||
before the document, you would override `relbar2` like this::
|
||||
|
||||
{% block relbar2 %}{% endblock %}
|
||||
|
||||
`rootrellink` / `relbaritems`
|
||||
Inside the relbar there are three sections: The `rootrellink`, the links
|
||||
from the documentation and the custom `relbaritems`. The `rootrellink` is a
|
||||
block that by default contains a list item pointing to the master document
|
||||
by default, the `relbaritems` is an empty block. If you override them to
|
||||
add extra links into the bar make sure that they are list items and end with
|
||||
the :data:`reldelim1`.
|
||||
``rootrellink``, ``relbaritems``
|
||||
Inside the relbar there are three sections: The ``rootrellink``, the links
|
||||
from the documentation and the custom ``relbaritems``. The ``rootrellink``
|
||||
is a block that by default contains a list item pointing to the master
|
||||
document by default, the ``relbaritems`` is an empty block. If you
|
||||
override them to add extra links into the bar make sure that they are list
|
||||
items and end with the :data:`reldelim1`.
|
||||
|
||||
`document`
|
||||
The contents of the document itself. It contains the block "body" where the
|
||||
individual content is put by subtemplates like ``page.html``.
|
||||
``document``
|
||||
The contents of the document itself. It contains the block "body" where
|
||||
the individual content is put by subtemplates like ``page.html``.
|
||||
|
||||
.. note::
|
||||
In order for the built-in JavaScript search to show a page preview on
|
||||
the results page, the document or body content should be wrapped in an
|
||||
HTML element containing the ``role="main"`` attribute. For example:
|
||||
|
||||
.. sourcecode:: html+jinja
|
||||
HTML element containing the ``role="main"`` attribute. For example::
|
||||
|
||||
<div role="main">
|
||||
{% block document %}{% endblock %}
|
||||
</div>
|
||||
|
||||
`sidebar1` / `sidebar2`
|
||||
A possible location for a sidebar. `sidebar1` appears before the document
|
||||
and is empty by default, `sidebar2` after the document and contains the
|
||||
``sidebar1``, ``sidebar2``
|
||||
A possible location for a sidebar. ``sidebar1`` appears before the document
|
||||
and is empty by default, ``sidebar2`` after the document and contains the
|
||||
default sidebar. If you want to swap the sidebar location override this and
|
||||
call the `sidebar` helper:
|
||||
|
||||
.. sourcecode:: html+jinja
|
||||
call the ``sidebar`` helper::
|
||||
|
||||
{% block sidebar1 %}{{ sidebar() }}{% endblock %}
|
||||
{% block sidebar2 %}{% endblock %}
|
||||
|
||||
(The `sidebar2` location for the sidebar is needed by the ``sphinxdoc.css``
|
||||
(The ``sidebar2`` location for the sidebar is needed by the ``sphinxdoc.css``
|
||||
stylesheet, for example.)
|
||||
|
||||
`sidebarlogo`
|
||||
``sidebarlogo``
|
||||
The logo location within the sidebar. Override this if you want to place
|
||||
some content at the top of the sidebar.
|
||||
|
||||
`footer`
|
||||
``footer``
|
||||
The block for the footer div. If you want a custom footer or markup before
|
||||
or after it, override this one.
|
||||
|
||||
@@ -159,23 +157,23 @@ list of custom sidebars in the :confval:`html_sidebars` config value. Their use
|
||||
is deprecated in favor of separate sidebar templates, which can be included via
|
||||
:confval:`html_sidebars`.
|
||||
|
||||
`sidebartoc`
|
||||
``sidebartoc``
|
||||
The table of contents within the sidebar.
|
||||
|
||||
.. deprecated:: 1.0
|
||||
|
||||
`sidebarrel`
|
||||
``sidebarrel``
|
||||
The relation links (previous, next document) within the sidebar.
|
||||
|
||||
.. deprecated:: 1.0
|
||||
|
||||
`sidebarsourcelink`
|
||||
``sidebarsourcelink``
|
||||
The "Show source" link within the sidebar (normally only shown if this is
|
||||
enabled by :confval:`html_show_sourcelink`).
|
||||
|
||||
.. deprecated:: 1.0
|
||||
|
||||
`sidebarsearch`
|
||||
``sidebarsearch``
|
||||
The search box within the sidebar. Override this if you want to place some
|
||||
content at the bottom of the sidebar.
|
||||
|
||||
@@ -392,7 +390,6 @@ are in HTML form), these variables are also available:
|
||||
<a href="{{ next.link|e }}">{{ next.title }}</a>
|
||||
{% endif %}
|
||||
|
||||
|
||||
.. data:: page_source_suffix
|
||||
|
||||
The suffix of the file that was rendered. Since we support a list of
|
||||
@@ -424,14 +421,19 @@ are in HTML form), these variables are also available:
|
||||
A callable yielding the global TOC tree containing the current page, rendered
|
||||
as HTML bullet lists. Optional keyword arguments:
|
||||
|
||||
* ``collapse`` (``True`` by default): if true, all TOC entries that are not
|
||||
ancestors of the current page are collapsed
|
||||
``collapse``
|
||||
If true, all TOC entries that are not ancestors of the current page are
|
||||
collapsed.
|
||||
``True`` by default.
|
||||
|
||||
* ``maxdepth`` (defaults to the max depth selected in the toctree directive):
|
||||
the maximum depth of the tree; set it to ``-1`` to allow unlimited depth
|
||||
``maxdepth``
|
||||
The maximum depth of the tree. Set it to ``-1`` to allow unlimited depth.
|
||||
Defaults to the max depth selected in the toctree directive.
|
||||
|
||||
* ``titles_only`` (``False`` by default): if true, put only toplevel document
|
||||
titles in the tree
|
||||
``titles_only``
|
||||
If true, put only top-level document titles in the tree.
|
||||
``False`` by default.
|
||||
|
||||
* ``includehidden`` (``False`` by default): if true, the TOC tree will also
|
||||
contain hidden entries.
|
||||
``includehidden``
|
||||
If true, the ToC tree will also contain hidden entries.
|
||||
``False`` by default.
|
||||
@@ -454,7 +454,14 @@ There are also config values that you can set:
|
||||
looks like a signature, use the line as the signature and remove it from the
|
||||
docstring content.
|
||||
|
||||
If the signature line ends with backslash, autodoc considers the function has
|
||||
multiple signatures and look at the next line of the docstring. It is useful
|
||||
for overloaded function.
|
||||
|
||||
.. versionadded:: 1.1
|
||||
.. versionchanged:: 3.1
|
||||
|
||||
Support overloaded signatures
|
||||
|
||||
.. confval:: autodoc_mock_imports
|
||||
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
============
|
||||
Using Sphinx
|
||||
============
|
||||
|
||||
This guide serves to demonstrate how one can get started with Sphinx and covers
|
||||
everything from installing Sphinx and configuring your first Sphinx project to
|
||||
using some of the advanced features Sphinx provides out-of-the-box. If you are
|
||||
looking for guidance on extending Sphinx, refer to :doc:`/development/index`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
quickstart
|
||||
installation
|
||||
restructuredtext/index
|
||||
markdown
|
||||
configuration
|
||||
builders/index
|
||||
extensions/index
|
||||
theming
|
||||
advanced/intl
|
||||
advanced/setuptools
|
||||
advanced/websupport/index
|
||||
@@ -12,9 +12,13 @@ Installing Sphinx
|
||||
Overview
|
||||
--------
|
||||
|
||||
Sphinx is written in `Python`__ and supports Python 3.5+.
|
||||
Sphinx is written in `Python`__ and supports Python 3.5+. It builds upon the
|
||||
shoulders of many third-party libraries such as `Docutils`__ and `Jinja`__,
|
||||
which are installed when Sphinx is installed.
|
||||
|
||||
__ https://docs.python-guide.org/
|
||||
__ https://docutils.sourceforge.io/
|
||||
__ https://jinja.palletsprojects.com/
|
||||
|
||||
|
||||
Linux
|
||||
|
||||
+27
-13
@@ -2,21 +2,38 @@
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
Once Sphinx is :doc:`installed </usage/installation>`, you can proceed with
|
||||
setting up your first Sphinx project. To ease the process of getting started,
|
||||
Sphinx provides a tool, :program:`sphinx-quickstart`, which will generate a
|
||||
documentation source directory and populate it with some defaults. We're going
|
||||
to use the :program:`sphinx-quickstart` tool here, though its use is by no means
|
||||
necessary.
|
||||
Sphinx is a *documentation generator* or a tool that translates a set of plain
|
||||
text source files into various output formats, automatically producing
|
||||
cross-references, indices, etc. That is, if you have a directory containing a
|
||||
bunch of :doc:`/usage/restructuredtext/index` or :doc:`/usage/markdown`
|
||||
documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX),
|
||||
man pages and much more.
|
||||
|
||||
Sphinx focuses on documentation, in particular handwritten documentation,
|
||||
however, Sphinx can also be used to generate blogs, homepages and even books.
|
||||
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
|
||||
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
|
||||
</usage/restructuredtext/index>`.
|
||||
|
||||
For a great "introduction" to writing docs in general -- the whys and hows, see
|
||||
also `Write the docs`__, written by Eric Holscher.
|
||||
|
||||
.. __: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
|
||||
|
||||
|
||||
Setting up the documentation sources
|
||||
------------------------------------
|
||||
|
||||
The root directory of a Sphinx collection of :term:`reStructuredText` document
|
||||
sources is called the :term:`source directory`. This directory also contains
|
||||
the Sphinx configuration file :file:`conf.py`, where you can configure all
|
||||
aspects of how Sphinx reads your sources and builds your documentation. [#]_
|
||||
The root directory of a Sphinx collection of plain-text document sources is
|
||||
called the :term:`source directory`. This directory also contains the Sphinx
|
||||
configuration file :file:`conf.py`, where you can configure all aspects of how
|
||||
Sphinx reads your sources and builds your documentation. [#]_
|
||||
|
||||
Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
|
||||
source directory and creates a default :file:`conf.py` with the most useful
|
||||
@@ -26,9 +43,6 @@ configuration values from a few questions it asks you. To use this, run:
|
||||
|
||||
$ sphinx-quickstart
|
||||
|
||||
There is also an automatic "API documentation" generator called
|
||||
:program:`sphinx-apidoc`; see :doc:`/man/sphinx-apidoc` for details.
|
||||
|
||||
|
||||
Defining document structure
|
||||
---------------------------
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
.. highlight:: python
|
||||
|
||||
.. _html-themes:
|
||||
|
||||
HTML
|
||||
====
|
||||
|
||||
|
||||
@@ -1036,39 +1036,71 @@ class DocstringSignatureMixin:
|
||||
Mixin for FunctionDocumenter and MethodDocumenter to provide the
|
||||
feature of reading the signature from the docstring.
|
||||
"""
|
||||
_new_docstrings = None # type: List[List[str]]
|
||||
_signatures = None # type: List[str]
|
||||
|
||||
def _find_signature(self, encoding: str = None) -> Tuple[str, str]:
|
||||
if encoding is not None:
|
||||
warnings.warn("The 'encoding' argument to autodoc.%s._find_signature() is "
|
||||
"deprecated." % self.__class__.__name__,
|
||||
RemovedInSphinx40Warning, stacklevel=2)
|
||||
|
||||
# candidates of the object name
|
||||
valid_names = [self.objpath[-1]] # type: ignore
|
||||
if isinstance(self, ClassDocumenter):
|
||||
valid_names.append('__init__')
|
||||
if hasattr(self.object, '__mro__'):
|
||||
valid_names.extend(cls.__name__ for cls in self.object.__mro__)
|
||||
|
||||
docstrings = self.get_doc()
|
||||
self._new_docstrings = docstrings[:]
|
||||
self._signatures = []
|
||||
result = None
|
||||
for i, doclines in enumerate(docstrings):
|
||||
# no lines in docstring, no match
|
||||
if not doclines:
|
||||
continue
|
||||
# match first line of docstring against signature RE
|
||||
match = py_ext_sig_re.match(doclines[0])
|
||||
if not match:
|
||||
continue
|
||||
exmod, path, base, args, retann = match.groups()
|
||||
# the base name must match ours
|
||||
valid_names = [self.objpath[-1]] # type: ignore
|
||||
if isinstance(self, ClassDocumenter):
|
||||
valid_names.append('__init__')
|
||||
if hasattr(self.object, '__mro__'):
|
||||
valid_names.extend(cls.__name__ for cls in self.object.__mro__)
|
||||
if base not in valid_names:
|
||||
continue
|
||||
# re-prepare docstring to ignore more leading indentation
|
||||
tab_width = self.directive.state.document.settings.tab_width # type: ignore
|
||||
self._new_docstrings[i] = prepare_docstring('\n'.join(doclines[1:]),
|
||||
tabsize=tab_width)
|
||||
result = args, retann
|
||||
# don't look any further
|
||||
break
|
||||
for j, line in enumerate(doclines):
|
||||
if not line:
|
||||
# no lines in docstring, no match
|
||||
break
|
||||
|
||||
if line.endswith('\\'):
|
||||
multiline = True
|
||||
line = line.rstrip('\\').rstrip()
|
||||
else:
|
||||
multiline = False
|
||||
|
||||
# match first line of docstring against signature RE
|
||||
match = py_ext_sig_re.match(line)
|
||||
if not match:
|
||||
continue
|
||||
exmod, path, base, args, retann = match.groups()
|
||||
|
||||
# the base name must match ours
|
||||
if base not in valid_names:
|
||||
continue
|
||||
|
||||
# re-prepare docstring to ignore more leading indentation
|
||||
tab_width = self.directive.state.document.settings.tab_width # type: ignore
|
||||
self._new_docstrings[i] = prepare_docstring('\n'.join(doclines[j + 1:]),
|
||||
tabsize=tab_width)
|
||||
|
||||
if result is None:
|
||||
# first signature
|
||||
result = args, retann
|
||||
else:
|
||||
# subsequent signatures
|
||||
self._signatures.append("(%s) -> %s" % (args, retann))
|
||||
|
||||
if multiline:
|
||||
# the signature have multiple signatures on docstring
|
||||
continue
|
||||
else:
|
||||
# don't look any further
|
||||
break
|
||||
|
||||
if result:
|
||||
# finish the loop when signature found
|
||||
break
|
||||
|
||||
return result
|
||||
|
||||
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
|
||||
@@ -1076,9 +1108,8 @@ class DocstringSignatureMixin:
|
||||
warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated."
|
||||
% self.__class__.__name__,
|
||||
RemovedInSphinx40Warning, stacklevel=2)
|
||||
lines = getattr(self, '_new_docstrings', None)
|
||||
if lines is not None:
|
||||
return lines
|
||||
if self._new_docstrings is not None:
|
||||
return self._new_docstrings
|
||||
return super().get_doc(None, ignore) # type: ignore
|
||||
|
||||
def format_signature(self, **kwargs: Any) -> str:
|
||||
@@ -1088,7 +1119,11 @@ class DocstringSignatureMixin:
|
||||
result = self._find_signature()
|
||||
if result is not None:
|
||||
self.args, self.retann = result
|
||||
return super().format_signature(**kwargs) # type: ignore
|
||||
sig = super().format_signature(**kwargs) # type: ignore
|
||||
if self._signatures:
|
||||
return "\n".join([sig] + self._signatures)
|
||||
else:
|
||||
return sig
|
||||
|
||||
|
||||
class DocstringStripSignatureMixin(DocstringSignatureMixin):
|
||||
@@ -1170,6 +1205,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ
|
||||
|
||||
documenter = FunctionDocumenter(self.directive, '')
|
||||
documenter.object = func
|
||||
documenter.objpath = [None]
|
||||
sigs.append(documenter.format_signature())
|
||||
|
||||
return "\n".join(sigs)
|
||||
|
||||
@@ -17,3 +17,9 @@ class C:
|
||||
class D:
|
||||
def __init__(self):
|
||||
"""D(foo, bar, baz)"""
|
||||
|
||||
|
||||
class E:
|
||||
def __init__(self):
|
||||
"""E(foo: int, bar: int, baz: int) -> None \\
|
||||
E(foo: str, bar: str, baz: str) -> None"""
|
||||
@@ -346,6 +346,10 @@ def test_autoclass_content_and_docstring_signature_class(app):
|
||||
'',
|
||||
'.. py:class:: D()',
|
||||
' :module: target.docstring_signature',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: E()',
|
||||
' :module: target.docstring_signature',
|
||||
''
|
||||
]
|
||||
|
||||
@@ -375,6 +379,11 @@ def test_autoclass_content_and_docstring_signature_init(app):
|
||||
'',
|
||||
'.. py:class:: D(foo, bar, baz)',
|
||||
' :module: target.docstring_signature',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: E(foo: int, bar: int, baz: int) -> None',
|
||||
' E(foo: str, bar: str, baz: str) -> None',
|
||||
' :module: target.docstring_signature',
|
||||
''
|
||||
]
|
||||
|
||||
@@ -409,6 +418,11 @@ def test_autoclass_content_and_docstring_signature_both(app):
|
||||
'.. py:class:: D(foo, bar, baz)',
|
||||
' :module: target.docstring_signature',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: E(foo: int, bar: int, baz: int) -> None',
|
||||
' E(foo: str, bar: str, baz: str) -> None',
|
||||
' :module: target.docstring_signature',
|
||||
'',
|
||||
]
|
||||
|
||||
|
||||
|
||||
Reference in new issue
Block a user