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.
In LaTeX output, all admonitions now also have a title row with icon.
The ``xcolor`` LaTeX package is now required and the ``fontawesome5`` LaTeX package is needed for the icons.
Consider the following piece of reST::
.. automodule:: sphinx.ext.autosummary
:members:
.. autosummary::
sphinx.ext.autosummary.Autosummary
This inserts an autosummary after the module docstring, but before
the members of the module. Without the change in this commit, this
would fail because `import_by_name` would attempt to import::
sphinx.ext.autosummary.sphinx.ext.autosummary.Autosumary
because the prefix (from the parent) is `sphinx.ext.autosummary`,
and the name is `sphinx.ext.autosummary.Autosummary`, which is able
to be imported from `sphinx.ext.autosummary`, but is not the way
that anyone would want to refer to it.
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Currently there is no mechanism to identify totally undocumented modules
in the coverage builder, unlike with partially documented modules.
Resolve this by introducing a new ``coverage_modules`` config option.
This is a list of modules that should be documented somewhere
within the documentation tree.
Any modules that are specified in the configuration value but
are not documented anywhere will result in a warning.
Likewise, any modules that are not in the config option but
are documented somewhere will result in a warning.
Signed-off-by: Stephen Finucane <stephen@that.guru>
- Remove now-removed configuration values
- Use obvious 'unset' defaults for ``project`` and ``author``
- Prefer 'e.g.' to 'ex.'
- Allow non-list sequence types in various configuration values
- Add types and defaults to every confval directive
- Put pip and conda as the most common options first
- Don't distinguish Linux / Windows in the pip commands.
- Replace the venv instructions by a general tip to use environments and link out for details.
- Collect all OS-specific package manager in one section
- Remove the "Windows - Other methods" secion.
- Move latest development release to a separate entry.
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
Eliminate type-related warnings when users configure a valid integer value for the `linkcheck_rate_limit_timeout` config setting.
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.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.
