A common use-case is that users simply want to point Sphinx
towards a Python module, and have it generate documentation
automatically.
This is not possible currently, without a "pre-build" step
of running the ``sphinx-autogen`` CLI.
This PR adds ``sphinx.ext.apidoc`` as a first-party extension,
to incorporate the source file generation into the Sphinx build.
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
This PR adds the `collapsible` and option to the core admonition type directives, which are propagated to the nodes, e.g.
```restructuredtext
.. admonition:: title
:collapsible:
content
.. note:: content
:collapsible: closed
```
For the HTML5 writer, this replaces the outer `div` with a `details` tag, and the title `p` with a `summary` tag (with an `open` attribute if set), e.g.
```html
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>hallo</p>
</div>
```
changes to
```html
<details class="admonition note" open="open">
<summary class="admonition-title">Note</summary>
<p>hallo</p>
</details>
```
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
The previous `UnreferencedFootnotesDetector` transform was untested and missed warnings for a number of cases.
This commit adds a test, to cover a reasonable range of scenarios,
then changes how the detection works to pass this test.
The transform now runs just after the docutils `Footnote` resolution transform
(changing its priority from 200 to 622)
then simply check for any footnotes without "back-references".
Use `include-read` instead of `source-read` for special content transform.
In-particular, this fixes an issue that `docs/changes.rst` would not re-build, when `CHANGES.rst` was changed.
This commit adds a `level` option to the `rubric` directive, which propagates a `level` attribute to the `rubric` node,
and allows renderers to select a specific heading level.
Logic for this attribute has been added to the HTML5 and LaTeX builder.
Sphinx (+ extensions) has a lot of available configuration variables for users,
allowing for the co-location of a short description on the configuration value,
can be utilised by external tools to provide better sphinx authoring support.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
- Remove "Site navigation" header
- this is already contextually clear (especially since separators were added in #12439)
- Hide "On this page" if `display_toc is False`
- Format "On this page" header similar to top-level site-nav sections
This commit is intended to improve new user's first-interaction with the Sphinx site:
- Make page header icon/text smaller and not capitalized
- Give min-width to left sidebar (it was getting too small at certain window sizes)
- Replace features list on landing page with admonition boxes, with adaptive layout
- Add landing page "used by" section
- Slightly restructure the Extension section, into Tutorials and How-tos
- Add code to `conf.py` to write HTML write redirect pages for moved documents
- Improve support page, by adding link to Stackoverflow, GH discussion and ReadtheDocs,
and remove defunct link to libera chat and matplotlib tutorial
A common "gotcha" of re-running `sphinx-autogen`, is that if there are changes it will not remove old files, leading to build errors for files not in a `toctree`
This commit introduces a `--remove-old` option to remove these files.
Note, a key detail here is that we don't want to simply clear the directory before running `sphinx-autogen`,
since this would lead to all files having a new `mtime`,
and then `sphinx-build` would rebuild all of them even if they have not changed.
So we must first collect the list of all correct files, then remove any not in the list.
A common "gotcha" of re-running `sphinx-apidoc`, is that if the modules API changes it will not remove old files, leading to build errors for files not in a `toctree`
This commit introduces a `--remove-old` option to remove these files.
Note, a key detail here is that we don't want to simply clear the directory before running `sphinx-apidoc`,
since this would lead to all files having a new `mtime`,
and then `sphinx-build` would rebuild all of them even if they have not changed.
So we must first collect the list of all correct files, then remove any not in the list.
The commit also improves some typing of the code and replace `os.path` by `pathlib.Path` in most instances
Split the events callback API into a separate document, add a flow graph of the events within the build process, add parameters to the events,
and link the `EnvironmentCollector` docs to the relevant events.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This commit:
- annotates the `Builder`'s "core" methods, with [`final`](https://docs.python.org/3/library/typing.html#typing.final)
- adds a UML graph to the Builder API docs
- Adds more methods to the Builder API docs
to make it clearer for extension developers, what is expected from a new builder subclass.
This commit removes `_write_doc_doctree_cache` from the pickled `BuildEnvironment`,
greatly reducing the on-disk and parallel forking memory consumption,
and ensuring outdated doctrees are not used for re-builds.
Some extensions cache data outside of the `BuildEnvironment` (usually for memory/performance reasons).
For these extensions, it would be helpful to detect when `sphinx-build -E` has been called, which in essence suggests the user wishes to remove cached data before building.
This commit adds the `Sphinx.fresh_env_used` public property, exposing `Sphinx._fresh_env_used` in an immutable manner.
This commit allows access to the `Parser` instance during the read phase, using the read-only property `BuildEnvironment.parser`.
This aims to allow for parser agnostic logic within roles and directives,
as opposed to hard-coding for implementation details of the default docutils `RSTParser`.
As a user and/or extension developer, it can be a source of confusion when,
on performing a `sphinx-build` for a cached project,
an unchanged configuration variable is always marked as changed (triggering a full rebuild).
This is often due to the variable being an unpicklable value,
which is silently omitted from the cache (i.e. the `environment.pickle`).
This commit introduces a specific warning for when a configuration variable is omitted from the cache,
allowing users to understand the root of the problem.
The key issue this commit seeks to address, is that existing tools / documentation often lead users to mistakenly use object types and not role names, a classic example being `function` not `func`
Previously, the warning message for using e.g. `` external:function`target` `` (with `py` as the default domain), would be:
```
WARNING: role for external cross-reference not found: function
```
This gives no information to the user on how to fix the issue, even though there is actually quite an easy fix
This commit adds logic to create more specific / helpful warning messages, e.g.
```
WARNING: role for external cross-reference not found in domains 'py', 'std': 'function' (perhaps you meant one of: 'py:func', 'py:obj')
```
This goes through the same original logic but, if the role is not found, it will look if the role name is actually an available object type on the domain(s), and then suggest its related roles.
This commit also reverts #12133, which provided a (silent) fallback to auto convert an object type to a role name.
Add `tests/test_theming/test_theming.py::test_theme_builds`, which is a parametrized test against all builtin sphinx HTML themes, that tests:
1. that the themes builds without warnings for a basic project, and
2. that all `.html` files it produces are valid XML (see https://html.spec.whatwg.org/)
https://pypi.org/project/defusedxml/ was added to the test dependencies, in order to safely parse the XML
This required one fix for `sphinx/themes/basic/search.html`, and one for `sphinx/themes/bizstyle/layout.html`
Also, `tests/test_theming` was removed from the `ruff format` exclude list
This type alias has now been fully documented for public consumption.
This will be beneficial to the sphinx ecosystem,
to aide/encourage extension developers to provide the correct metadata.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This commit overrides the `SphinxLoggerAdapter.warning` method,
to provide documentation and type annotations specific to logging sphinx warnings.
This should aide sphinx core/extension developers in creating good warnings.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: danieleades <33452915+danieleades@users.noreply.github.com>
This comit removes select sphinx top-level modules from the `ruff format` exclude list.
They were selected based on the fact that they have the least diffs when formatted,
are not believe to introduce changes that would adversely affect any existing PRs.
This commit fixes the issue of `objects.inv` denoting object names, whilst the `external` role only allows for role names.
As an example, take the `objects.inv` for the sphinx documentation, which contains:
```
py:function
compile : usage/domains/python.html#compile
```
A user might understandably expect that they could reference this using `` :external:py:function:`compile` ``, but actually this would previously error with:
```
WARNING: role for external cross-reference not found: py:function
```
this is because, `function` is the object type, yet `external` expects the related role name `func`.
It should not be necessary for the user to know about this distinction,
so in this commit, we add logic, to first look if the name relates to a role name (as previous, to not be back-breaking) but, if not, then also look if the name relates to an object that has a known role and, if so, use that.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Chris SewellandAdam Turner
