- 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.
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`.
