At present, some attributes of env object are considered as optional
because they have been initialized by None on the constructor. But
they have always been fullfilled actually.
To be clear the type hints of the env object, this makes the `app`
argument for the BuildEnvironment class required. It can ensure the
attributes of env object are not optional.
Since 1.6, sphinx.util.logging module became the default logging
interface of Sphinx. It allows sphinx-components to output log
without the app (or env) object. According to the policy,
DocumenterBridge.warn() is no longer needed and should be replaced by
the logging module.
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.
To choose appropriate content for pending_xref node on resolving,
this introduces a new custom node `pending_xref_condition`. It only
has a condition for the filtering and contents of the reference.
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
To embed the external favicon and logo image, this adds new template
variable `favicon_url` and `logo_url` that point the external URL or
relative path for the favicon/logo file from current file. It helps to
use it on template files.
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.
These attributes were used to cache checked links and avoid issuing
another web request to the same URI.
Since 82ef497a8c, links are pre-processed
to ensure uniqueness. This caching the results of checked links is no
longer useful.
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
To keep compatibility with the standard doctree model of docutils,
this stops to use 'default' value as a default value of the align
attribute for figure and table nodes.
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).
I'm very happy to see that the events in Sphinx have been laid out in order as they have been in this doc.
With that being said the notation I noticed was a bit odd. Some of the items in the list refer to events and as a result,
parenthesis are used to indicate the beginning and end of the parameters that the event takes.
In other items in the list, parenthesis are used for additional context for an event. The combination of some particularly very long lines,
the intermixing of comments, pseudo-code, indentation of items following a `for` or an `if` made this very difficult to read on a mobile device.
As a result, I've added whitespace, fixed a typo, reduced the length of some lines by moving them to a new line, and removed all `()` that were not
present to indicate parameters fed to a function.
The utility function movefile() was added in
677d096393 to handle existing files on
Windows. Since Python 3.3, the stdlib function os.replace() fills this
role.
This deprecates `no_docstring` argument for Documenter.add_content().
After this change, please use Documenter.get_doc() to control (suppress)
the content of the python object.
At present, the implementation of Documenter.get_object_members() is
only for class objects. In fact, no subclasses use it (all of them are
overriding the method).
This deprecates Documenter.get_object_members() and copies it to
ClassDocumenter.get_object_members().
This method always returns False, it is dead code. The exception
checking stopped working because Requests library wraps SSL errors in a
`requests.exceptions.SSLError` and no longer throws an
`urllib3.exceptions.SSLError`. The first argument to that exception is
an `urllib3.exceptions.MaxRetryError`.
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.
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.
In #7487, SingledispatchFunctionDocumenter is merged into
FunctionDocumenter. SingledispatchMethodDocumenter is also. As a result,
They are no longer needed. So this deprecates them.
This postpones the evaluation of LaTeX packages via
``app.add_latex_package()`` to just before writing .tex file. That
allows extensions to add LaTeX packages during reading and resolving
phase.
The texinfo writer remembers the current desc node to render
a desc_annotation node. This makes the mechanism robust to support
nested object descriptions.
The handler searches autosummary_toc node under root of document and
just under section nodes. But that is already done in
ToctreeCollector.process_doc(). So it's no longer needed.
As a successor of sphinx.util.inspect.Singnature, this adds
signature() function behaves like `inspect.signature()`. It is
very similar to way of python's inspect module.
In addition, this also adds stringify_annotation() helper to
sphinx.util.inspect module. With these two functions, we can move
to python's Signature object to represent function signatures
perfectly. It's natural design for python developers than ever.
