The implementation of the standard domain so far has considered the
first child of the rubric node is the title of the rubric. But it can
may multiple nodes when the rubric title is marked up.
This extracts the title of the rubric from the whole of the children
of it.
This changes the structure of `highlight_options` to a dictionary that
maps language names to option dictionary. It allows to setting pygments
options for multiple languages at once.
To make CSS customizable, all CSS files in basic/layout.html has their
priority: 200. Therefore, extensions and users can insert their own
custom CSS files before or just after them.
As a side effect, the CSS tags in basic/layout.html are removed. These
CSS files will be rendered via `css_files` template variable.
refs: #8634, c5f0398010
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.
An empty `__all__` should be represented as "there is no public items".
But autodoc considers all items on the module are public. This changes
the behavior to correct one.
To control the visibility of variables, ModuleDocumenter have to load
docstring of them on `get_object_members()` phase. This reimplements
it and `get_module_members()` helper to fetch docstring on earlier
phase (as ClassDocumenter does).
autodata and autoattribute directives does not show right-hand value of
the variable if its docstring contains ``:meta hide-value:`` in
info-field-list.
Deprecate `no_docstring` argument for `Documenter.add_content()` again.
At the first trial (#8533), it changes the behavior of
`autodoc-process-docstring` event; it is emitted unexpectedly for an
alias of class. But it brings an incompatible change to extensions.
Hence it was partially reverted at #8581.
This keeps not calling the event for an alias of class. To do that,
now `Documenter.get_doc()` can return None value.
Linkcheck organizes the URLs to checks in a PriorityQueue. The items are
tuples (priority, url, docname, lineno).
Tuples where the lineno is `None` are not comparable with tuples that
have an integer lineno, and PriorityQueue items must be comparable (see
https://bugs.python.org/issue31145).
Fixes an issue when a document contains two links to the same URL, one
with an int line number and the other without line number metadata (such
as an image :target: attribute).
Using 0 instead of None to represent no line number should not lead to
observable changes, the result logger only logs the line number when it
is truthy.
Close#8565
The instance attributes on subclasses are shown on the document of
parent class unexpectedly because of autodoc modifies `__annotations__`
in place. This fix creates a copy of `__annotations__` attribute and
attach it to the subclass.
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.
To support instance attributes on super class, get_class_members() scans
the instance attributes defined at super classes using ModuleAnalyzer.
It allows to generate document for them when users gives :
inherited-members: option.
To avoid filtering __slots__ attributes having docstring at
filter_members(), this passes docstring captured at get_class_members()
to the filter_members() via ObjectMember.
So far, autodoc obtains type annotations of instance attributes by
ModuleAnalyzer directly. As a result, autodoc_type_aliases are ignored
for these variables.
This goes to merge type annotations from the class itself and
ModuleAnalyzer's, and get type annotations using `typing.get_type_hints()`
to apply autodoc_type_aliases.
So far, autoattribute uses "given class name" to fetch comments of
uninitialized instance attributes. But pycode expects to use "real"
class name on searching attribute comments.
This adds UninitializedInstanceAttributeMixin to handle it simply.
Previously, the nonascii_srcdir in tests/test_build.py contained some
logic to attempt to handle the case where non-ascii directories aren't
supported, but it did not actually work because it fails to copy the
test sources to the temporary directory.
With this commit, the following test invocation, which previously
failed, now pases:
LANG=en_US.iso8859-1 python -m pytest test_build.py
Since v2.3, Sphinx supports uplatex as an alternative of latex_engine for Japanese
docs (refs: #4186, #6841). uplatex is able to build a document without conversion
character encoding internally. It allows using unicode characters in documents.
Additionally, uplatex is compatible with platex (current default latex_engine for
Japanese docs).
This changes the default latex_engine for Japanese document to uplatex.
In HTML, consecutive spaces are considered as single space by HTML
browsers. To represent them as is, we have to escape them on rendering
them into HTML. This starts to escape the whole of desc_signature node.
A custom type defined by typing.NewType was rendered as a function
because the generated type is a function having special attributes.
This renders it as a variable.
Note: The module name where the NewType object defined is lost on
generating it. So it is hard to make cross-reference for these custom
types.
Clears warning:
tests/test_build_linkcheck.py::test_connect_to_selfsigned_with_tls_cacerts
tests/test_build_linkcheck.py::test_connect_to_selfsigned_with_requests_env_var
…/venv/lib/python3.8/site-packages/urllib3/connection.py:455: SubjectAltNameWarning: Certificate for localhost has no `subjectAltName`, falling back to check for a `commonName` for now. This feature is being removed by major browsers and deprecated by RFC 2818. (See https://github.com/urllib3/urllib3/issues/497 for details.)
warnings.warn(
Test `test_connect_to_selfsigned_nonexistent_cert_file` serves two
purposes:
- verify the behavior when the CA bundle file path is incorrect
- flag a leak of REQUESTS_CA_BUNDLE
Assumes that test runs after
`test_connect_to_selfsigned_with_requests_env_var`. Not great, but
better than no testing.
`linkcheck` logic suggests that SSL errors were originally expected to
be ignored.
Blaming the corresponding lines point to issue #3008: linkcheck to
website with self-signed certificates. That issue was fixed by commit
4c7bec6460, which ignored SSL errors.
Probably because back then, users could not specify a CA bundle.
A broken SSL certificate is a real issue, it should not be ignored.
Users wishing to ignore issues for a specific link can use the
`linkcheck_ignore` option.
The current behavior is to report the site as broken, keep it.
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.
As typing.get_type_hints() doing, this adds Optional[t] to type
annotations if a default value equal to None is set.
Note: this is default behavior of inspect.signature() since Python 3.10.
Makes the test more realistic by issuing an HTTP request.
Reduces coupling between test and the code under test.
The `http_server` helper was factored out into a new tests.utils module.
Usually we use "Any" type for the type annotation which takes any kinds
of types, instead of "object" class. So this replaces "object" to "Any"
in our example.
In #7651, autodoc stops to undecorate the functions on getting the
signature from the callables. But some kinds of decorators conceals
the correct signature because they pass through their arguments via
`(*args, **kwargs)`.
This restarts to undecorate the functions again as before #7651.
They are sometimes failed with python3.5 because the order of singledispatch
functions is not stable on python 3.5. This uses comparision via "in"
keyword to check the signature of singledispatch functions stably.
This allows `autodoc-skip-member` handlers to determine whether a member
not included in `__all__` attribute of the module should be documented or
not.
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.
I found test-root defines rst_epilog in its conf.py. It causes
side-effects to many test cases in Sphinx's testing because test-root
is widely used. This removes the configuration from test-root not to
cause side-effects to our testings.
Note: We already have test cases for rst_epilog in test_util_rst.
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+.
Developers can write number literals in several ways. For example,
decimal (1234), hexadecimal (0x1234), octal decimal (0o1234) and so on.
But, AST module don't mind how the numbers written in the code. As a
result, ast.unparse() could not reproduce the original form of number
literals.
This allows to construct number literals as possible using original
source code.
Note: This is only available in Python 3.8+.
Our document describes that users can override system messages via
their own message catalog named `sphinx.mo` under the locale_dirs.
But it has not been used since its beginning of i18n mechanism because
the priority of users' message catalog is lower than system's.
This makes the priority of users' message catalog higher than system's.
Typically, the __args__ attribute of type annotations is a tuple
containing arguments for the types (ex. The __args__ of `List[int]` is
`(int,)`). But some kind of types has non tuple __args__ attribute.
For example, `nptyping.NDArray` is one of them.
This fixes the TypeError when the invalid __args__ attribute found.
Add a new config variable; man_make_section_directory to make a
section directory on build man page. During 3.x, it defaults to
False and will be changed to True on 4.0 release.
Trailing whitespace do not have impact on the result, they are just
unused bytes. Most text editors are configured to strip trailing
whitespaces. Remove them all in one go.
Update a handful of files to use the UNIX line ending.
autodoc raises a parsing error if some extension generates a docstring
not having blank lines at the tail. This appends a blank line if
generated one does not contain it.
When documenting classes derived from typing.Generic (essentially all classes in the
typing module) the constructor signature would show an unhelpful (*args, **kwds).
typing.Generic has a __new__ method which was picked up by sphinx. With this patch it
is skipped and constructor signatures for generic classes are shown as they should.
sphinx.util.inspect:isproperty() does not considers that
cached_property decorator that has been added since Python 3.8 is
a kind of properties. This fixes it.
`typing.get_type_hints()` raises NameError when the target object
contains unresolavable type annotation (ex. TYPE_CHECKING). This
handles the exception and use unresolved annotations for type hints.
An annotated instance variable on super class is not documented when
derived class has also other annotated instance variables because
`obj.__annotations__` is overrided by derived class's type hints.
To get annotations of the target class correctly, this scans MRO to
get all of annotated instance variables.
So far, napoleon converts multiple paramaters declrarations to single
paramaeter fields (`:param:` and `:type:`) unexpectedly. As a result,
the output seems broken.
This converts it to multiple parameter fields (a pair of field for each
parameter declration) to build parameter successfully.
Note: The conversion rule is available only when napoleon_use_params=True.
To control trimming doctest flags manually, this adds new options
:trim-doctest-flags: and :no-trim-doctest-flags: to doctest
directives. It helps to describes doctest module itself in python
doc (see #6698).
