The type union operator (PEP-604) causes autodoc crashed in python 3.9
or below because of the syntax is not suppoerted yet in the interpreters.
Internally, `typing.get_type_hints()` raises TypeError on evaluating the
annotation by BitOr operator for types.
To avoid the crash, this adds a fallback not to evaluate the annotations
and keep as is. As a side effect, `autodoc_type_aliases` will not work
for the modules and classes that uses type union operator for their
annotations.
Unintentionally, uninitialized attributes defined at superclasses are
recognized as undocumented in the filtering step. Therefore, they are
filtered if `:undoc-members:` option given.
This is cosmetic as the blank line starting varwidth environment used
for merged table cells in latex output changed nothing to PDF.
Nevertheless I extended a unit test to have a multi-paragraph merged
cell using varwidth. What is important is that \sphinxAtStartPar line
itself is never followed by blank line.
Instead of using application members to access the builder and trigger a
build, use the main app interface.
It ensures the builder setup is realistic, builder cleanups are executed
and the build-finished events are emitted.
As discussed in #7879, the default style of line numbers for code
blocks in HTML output becames 'inline' by default. And 'table' style
is now deprecated and will be removed in Sphinx-6.0.
autodoc crashed when a decorator in mocked module takes arguments
because mock system returns the first argument for the decorator as a
decorated object.
This changes the approach for mocking decorators that remembers
arguments for each decoration, and fetch the latest argument on
generating document.
Add new configuration variables: `html_permalinks` and
`html_permalinks_icon`.
This refines the settings around HTML permalinks.
* html_add_permalinks
* Deprecated.
* html_permalinks
* Enable or disable permalinks feature.
* html_permalinks_icon
* Change the icon for permalinks
sphinx-apidoc should generate a namespace module file when
`--implicit-namespace` option given. This fixes the case the namespace
module has subpackages, but no submodules.
The anchors for viewcode was generated in the reading phase only if
supported builder is used. It causes anchors are missing on the
incremental build after the build for non supported builder.
This introduces `viewcode_anchor` node to insert the anchor even if non
supported builders. They will be converted to the anchor tag in the
resolving phase for supported builders. Or, they will be removed for
non supported builders.
The module pages should be generated for epub only if enabled via
configuration. But they are generated after the build for other
viewcode-supported builders. This checks the current builder on
generating module pages.
This replaces times package with tgtermes and tgheros (clones of Times and
Helvetica with better LaTeX support) and the monospace font from txfonts
package (txtt). This font is better matched with Times-like fonts than
Courier clones.
The changes applies to pdflatex/platex/uplatex.
Fixes: #8711
So far, linkcheck scans all of references and images from documents, and
checks them parallel. As a result, some URL would be checked twice (or
more) by race condition.
This collects the URL via post-transforms, and removes duplicated URLs
before checking availability.
refs: #4303
`:download:` role creates duplicated copies when the document contains
two or more the role for the same file, but in different form. It
considers two paths are different when one contains relative path like
`path/to/../file.dat`.
Internally, `env.relfn2path()` does not normalize the given path in
relative form. As a result, download role can't detect the same paths
are given. This adds `os.path.normpath()` to `env.relfn2path()` to
normalize the path.
As a well-known idiom, mypy recommends to use ellipsis ("...") for
default argument values as a elided style. This allows to write the
style and helps to document it with copying the default argument
values from actual implementation.
Note: This does not copy the default argument value when the argument
of overloaded function has its own default value.
The default values for overloaded functions are rendered as string
literal unexpectedly because autodoc extracts code snippets from
the source code, not actual value (ex. int, ellipsis, and so on).
This introduces a simple wrapper class; `DefaultValue` to render these
code snippets like actual values, not string literals.
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.
