DocumenterBridge.filename_set has been used since its beginning. On the
other hand, in docutils, record_dependencies attribute is well-used to
store the list of dependency files. So this renames it to docutils'
standard attribute.
To make directives' behavior consistent, the :file: option for
csv-table directive now recognizes an absolute path as a relative
path from source directory.
Add a new extension `sphinx.ext.autodoc.preserve_defaults`.
It preserves the default argument values of function signatures in source code
and keep them not evaluated for readability. This is an experimental
extension and it will be integrated into autodoc core in Sphinx-4.0.
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.
To describe the purpose more accurately, the `master_doc` is now renamed
to `root_doc`. The old name is still available. But it is recommeneded
to use new one from now on.
So far, a TypeVar is rendered without module name. As a result, it
could not be resolved if it is imported from other modules. This
prepends its module name and make it resolvable. This is available
only in Python 3.7 or above.
As a side effect, all of TypeVars are displayed with module name. It
should be fixed in latter step (refs: #7119)
Resolved Conflicts:
sphinx/texinputs/sphinx.sty
Some hunks needed to go to sphinx/texinputs/sphinxlatexliterals.py,
others already belonged to split files.
To achieve this the simplest was to use also the \label/\ref mechanism
as for footnotes typeset using footnotetext. Removing the hack into
footnotehyper internal macro, we use an enriched scope, which will
enable references with same number to each generate correct links.
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.
