Since v0.2, python domain gives a special treatment for the exceptions
module to suppress its name on documenting exception classes. It had
been worthy on python2 era. But the module has been removed since
python3. Therefore, the special treatment becomes harmful for user
libraries. This removes it to render module names correctly.
Note: Now we've only supported python3. So this is not incompatible.
So far, DocFieldTransformer has split the field name for `:type:`
and `:param:` at the first whitespace. Therefore, it does not allow
to use a type containing whitespace (ex. `Dict[str, str]`).
This changes the splitting logic to divide the field name at the last
whitespace (a.k.a `rstrip()`). It allows to use whitespaces on types.
A duplicated warning is emitted when both canonical and its alias
objects are defined on the same document. But it should not be emitted
because they're the same object, not conflicted.
On parsing the types, the leading dot of the ellipsis (...) is considered
as a reference name. And its first dot is considered as a notation for
relative type reference (ex. ".ClassName"). As a result, it was converted
double dots unexpectedly.
This changes the parsing rule to treat the ellipsis as a symbol, not a
name.
Add a new config variable: python_use_unqualified_type_names. If enabled,
it goes to suppress the module name of the python reference if it can be
resolved.
Since its beginning, `:var:` field has created a cross-reference to the
attribute having the same name. It is meaningful only if the attribute
is documented by `py:attribute` directive. It means the `:var:` field
and `:attr:` role are almost the same and conflicted. Additionally,
the cross-reference points incorrect variable if the target is not
documented.
Thus, the cross-reference feature of `:var:` field is disabled.
The searching context like py:module and py:class are missing in the
pending_xref nodes generated from info-field-lists. This sets these
searching context info to them.
Keep imports alphabetically sorted and their order homogeneous across
Python source files.
The isort project has more feature and is more active than the
flake8-import-order plugin.
Most issues caught were simply import ordering from the same module.
Where imports were purposefully placed out of order, tag with
isort:skip.
To be clear the ambiguous warning for missing-reference :ref:,
this separates the warning to missing-label and missing-caption.
To emit a warning dynamically, this also adds a new event:
`warn-missing-reference` to customize warning messages via event
handlers.
Number literals in default argument value is converted to decimal form
unexpectedly by AST module. This fixes the signature parsing code to
recosntruct it correctly.
Note: This is only available in Python 3.8+.
In development of 3.0, Sphinx starts to obey to the rule of
"Identifier Normalization" of docutils. This extends it to allow
dots(".") and underscores("_") for node identifier.
It allows Sphinx to generate node identifier from source string as
possible as it is (bacause dots and underscores are usually used in
many programming langauges).
This change will keep not to break hyperlinks as possible.
In Python 3, the default encoding of source files is utf-8. The encoding
cookie is now unnecessary and redundant so remove it. For more details,
see the docs:
https://docs.python.org/3/howto/unicode.html#the-string-type
> The default encoding for Python source code is UTF-8, so you can
> simply include a Unicode character in a string literal ...
Includes a fix for the flake8 header checks to stop expecting an
encoding cookie.
Parameter and variable types in the Python domain have the
counter-intuitive behavior of matching instance methods (or likely any
other objects) rather than classes, e.g.:
```python
class Foo(object):
def list(self):
"""List some things."""
def bar(x):
"""
:param x: x
:type x: list
"""
```
`bar()` will link to `Foo.list()` rather than the standard library
`list` type.
Moved #3465 here, to address this in `stable` instead.
This fixes a problem with the Python domain object nesting. Because only one
object name was stored in `ref_context`, and reset to `None` in `after_content`,
nesting broke if you put anything after a nested class:
```rst
.. py:class:: Parent
.. py:method:: foo()
This wouldn't resolve: :py:meth:`bar`
.. py:class:: Child
In the `after_content` method, the object is reset to `None`, so
anything after this in the same nesting is considered to be top level
instead.
.. py:method:: bar()
This is top level, as the domain thinks the surrounding object is `None`
```
This depends on #3519 and can be rebased after that is merged into stable
Fixes#3065
Refs #3067
These are just the passing test cases for the domains currently. I am going to
patch up issues with nesting on both domains to start, so these are the test
cases I'll be testing against. I'll see about addressing the other core
domains, or at very least the cpp domain, with similar tests if this looks
okay.
So far, these tests only test against methods/functions for the basic nesting
structure. More complete tests will test additional domain roles.
Refs #662
* rename a few test modules to make the names more consistent
* do not copy/use Sphinx from build/ (unnecessary without 2to3)
* use a temporary dir for *all* test projects, the source tree
will stay pristine that way (default is tests/build)
* speed up tests by ~3x by splitting up test projects and avoiding
rebuilds
