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 adds a few changes to the theme to make it more readable and visually more appealing. In particular:
- Slightly increase the font weight of headings (300 --> 400).
- Adapt the color of the search box border to sphinx-blue.
- Add horizontal bars between the components of the side bar.
- Re-style admonitions to use colored title backgrounds.
The "alt" attribute of an `<img>` is required to convey all information.
Make it clear which logo is shown.
Also make it possible for users to override the logo_alt with a custom value.
This commit adds detection of ambiguous ``std:label`` and ``std:term`` references (due to case-insensitivity)
during loading and resolution of Intersphinx targets,
and emits a warning if found.
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
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.
This PR allows to serve JavaScript test fixtures using a fixture-based logic as for Python tests.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This explains the requirements for importablilty (can be found and dependencies can be resolved). It also explains two common approaches how this can be achieved.
Documentation needs to mention the new Transifex CLI tool instead of the deprecated transifex-client
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
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 allows statements executed within a ``progress_message`` context
to emit log messages without polluting the console output.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
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`.
The `defusedxml` dependency was added to `sphinx.testing` in sphinx 7.3,
but it is not part of the core sphinx dependencies, and not strictly necessary for the running of the pytest plugin.
This commit moves the import into the only function which uses it,
so that the pytest plugins can be used again without this dependency.
A reference like ":ref:`Some other page <some-other-page>`" results
in a refuri "#some-other-page". This does not seem useful to readers
of the man page. It is especially unhelpful when using a terminal
that implements a hint mode for selecting links -- the extra links
add noise, making it harder to select the interesting ones.
Don't emit OSC 8 for those.
