Add test to make sure Sphinx uses proper URL encoding for
special characters in file names.
Use test_html_download() since it test_html5_output() doesn't
quite seem to have easy pattern to verify the contents of href
attribute.
Issue #3097
Signed-off-by: Johannes Aalto <ext-johannes.aalto@vaisala.com>
This allows to inject a reST snippet through autodoc-process-bases
event. It helps to modify the base classes of any class to the expected
mark-up'ed text by custom extension.
This fixes an issue with warnings that have been raised with no subtype
being suppressed if a suppress warnings value with a subtype has been set.
e.g. all `autodoc` warnings should not be suppressed if
`autodoc.import_object` is only set to be suppressed.
In case of the descendants of generic class, the value of
obj.__orig_bases__ is incorrect because it returns original base
arguments for the child of the generic class instead of the target
class itself.
This uses obj.__dict__ to get the correct __orig_bases__ information.
Autodoc generates reST code that uses raw `:obj:` and `:class:` xrefs to
refer the classes and types. But they're fragile because they assume
the primary_domain=='py'.
This adds `:py:` prefix to these xrefs to make them robust.
Before 3.10, an instance of NewType has incorrect module name. But it
was fixed on 3.10. This starts to use the module info if the
interpreter is 3.10+.
Add an extra step in the autosummary summariser algorithm to get a valid
text form of section headings. This fixed issues when the first element
of a summarised document was a section heading with overlines, such as
=======
Heading
=======
Previously, the first line would be taken verbatim, which caused parse
errors in the rest of the document.
The `MethodDocumenter.get_doc` method added by
51ae283a38 prevents
DocstringSignatureMixin from working correctly for __init__ and
__new__ methods. Additionally, the __new__ docstring was not obtained
correctly.
This commit checks for `self._new_docstrings` being set, and also
corrects the logic for obtaining the __new__ docstring.
There still remains the issue that when the class signature is
obtained from the signature of __init__ or __new__, only the real
signature is used, due to the use of `sphinx.util.inspect.signature`;
the autodoc_docstring_signature option does not have any effect.
The approach of `rewrite_github_anchor` makes some anchors valid. But
it also makes other kind of anchors invalid. This disables the handler
to make them valid again (while 4.1.x release).
Merge request #9381 broke support for local logos/favicons as it
retained the paths that are passed to the template engine. That's wrong
as the actual path will be in _static/.
This should fix#9438
Right now, labels are emitted as part of a @footnote directive.
That results in e.g.
Note1: (@footnote{@w{(1)}
Future versions of GCC may zero-extend...
})
which is incorrect and should be rather:
Note1: (@footnote{Future versions of GCC may zero-extend...})
Now linkcheck builder integrates `linkcheck_warn_redirects` into
`linkcheck_allowed_redirects`. As a result, linkcheck builder will
emit a warning when "disallowed" redirection detected via
`linkcheck_allowed_redirects`.
Autoattribute directive should check the existence of instance attribute
that is defined inside __init__() but not having comments before
accessing it.
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.
`sphinx.util.inspect.getdoc()` clean the docstring up if the method is
inherited and not having docstring. That causes indentations are
removed on processing it.
After #9246, `find_pending_xref_conditions()` should be only called from
intended modules. At present, the Python Domain is the only module to
call it intendedly. Therefore, this removes the needless calls of the
utility function from "unintended" modules.
Add a new confval; `linkcheck_warn_redirects` to emit a warning when
the hyperlink is redirected. It's useful to detect unexpected redirects
under the warn-is-error mode.
Add `autodoc-process-bases` to modify the base classes of the class
definitions. This allows the extensions to insert or modify the list
of the base classes via event-handlers.
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.
The special members are not treated as "attributes". So they're not
handled by DataDocumenter. This moves the detection to the earlier
step of filter_members().
This new method in the `Sphinx` object allows extensions to communicate to
Sphinx that it's preferred to include HTML assets in all the pages. However,
it's extensions developers' responsability to follow this config and decide
whether or not include the assets required.
Extensions developers' can check `Sphinx.html_assets_in_all_pages` together with
any other logic they may have to decide if the assets will be included in the
rendered page or not.
Closes#9115
When multiple singledispatch decorators are stacked, the first typehints
are copied to the subsequent definitions unexpectedly.
Now autodoc generates a dummy function not to affect typehints to
subsequent functions.
Add `class-doc-from` option to the `autoclass` directive to control
the content of the specific class. It takes `class`, `init`, and `both`
like `autoclass_content`.
There is no docs and testcases for "None" argument of the program
directive. It has been implemented since very old version. But it's
not documented and tested long.
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 generating the base class information, unexpected nit-picky warning
for ``typing.Any`` was emitted. This fixes it by using `~` prefix on
generating a cross-reference to make it valid.
The imgconverter unexpectedly goes to convert even if the given image
is supported by the target builder when the image globbing is not used.
This enables format guess-ing on not globbed.
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 test objects so all builders gets exposed to the new nodes.
Make the fallback node post-transform change desc_inline as well.
Make the html4, latex, and text writers handle desc_inline.
Since v0.17, docutils starts to load language module on parsing reST
document using StateMachine directly. So far, our testcase uses invalid
language code for testing autosummary. This fixes it to work with new
docutils.
Since v0.17, docutils starts to use <figure> and <figcaption> for figure
and its caption on HTML output. This modifies the expected value of our
testcases to support it.
Add new tests to exercise the new autodoc_typehint_undoc option. Where
an existing test would have a meaningful behavior change with the new
option set to False, that test is copied, the new option is set to False
in the copy, and the assertions reflect the new expected behavior.
The new test test_autodoc_typehints_description_with_documented_init
illustrates the problem reported in #7329, and the new test
test_autodoc_typehints_description_with_documented_init_no_undoc
illustrates that this issue no longer occurs when the new
autodoc_typehint_undoc option is set to False.
This generates `:canonical:` option for `:py:class:` directive if the
target class is imported from other module. It allows users to refer it
using both the new name (imported name) and the original name (canonical
name).
It helps a library that implements some class in private module (like
`_io.StringIO`), and publish it as public module (like `io.StringIO`).
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.
