* Recommend importlib import mode for new projects
* Recommend src layout more strongly
* Switch to hatchling as the packaging tool in the example (following PyPA)
* Add explanation about the different import modes
New versions of sphinx starting showing `__init__` parameters even when
we don't want them to show because they are private (have `_ispytest`
argument).
The only working solution I found was to switch to
`autodoc_typehints_description_target = "documented"` and explicitly
document parameters for which we want to show the types. It's a little
tedious and repetitive in some simple cases, but overall it results in
nicer API docs.
`usage.rst` has been moved from `doc/en` to `doc/en/how-to`, so the `man_pages` configuration
value needs to be updated to the new location, so that we dont get this warning:
writing... WARNING: "man_pages" config value references unknown document usage
- Remove the index page https://docs.pytest.org/en/7.1.x/genindex.html
Such an index is reasonable in books but not so much in HTML pages.
IMHO the integrated search is much more user-friendly and sufficient.
- Remove the PDF link from the entry page. The PDF is already linked
in the sidebar. I anticipate that getting the PDF documentation is
not a major concern for users.
- Remove the sections "Changelog" and "License" from the entry page.
These section only contain links to the respective pages.
These topics are purely technical. They should be easily accessible
(which they still are through sidebar section "About the project"),
but they don't need additional advertisement through a dedicated
section on the entry page.
The PDF documentation on readthedocs was missing the figures in the
fixtures reference chapter. This PR uses a Sphinx plugin that
automatically converts the checked-in SVG files to the PDF input files
that LaTeX requires.
The SVG-to-PDF conversion is done by inkscape, which gave the best
conversion among the tools I tried. However, it [does not yet
understand][href-bug] that you can write a plain `href` instead of
`xlink:href` in svg files, so I’ve had to edit the SVG files
accordingly.
[href-bug]: https://github.com/TeX-Live/luatex.git
This configures Sphinx autodoc to include the type annotations
along with the description of the function/method, instead of including
it into the signature.
Fix#8405
This introduces a new role, `:globalvar:`, so we can mark/reference
variables like `pytest_plugins`, `pytestmark`, etc. This besides being useful
also makes the documentation look more consistent.
This allows for e.g. Jedi to infer types (it checks the name).
It was only used to support Python 3.5.0/3.5.1, where this is is not
available in the `typing` module.
Ref: https://github.com/davidhalter/jedi/issues/1472
Uses `TYPE_CHECKING = False` in `_pytest.outcomes` to avoid having to
work around circular import.
Now `tox -e docs` will also include the draft changelog for the
next version (locally only).
`CHANGELOG.rst` now only points to the changelog on READTHEDOCS so
sphinx diretives can be used.
Followup to https://github.com/pytest-dev/pytest/pull/6272
This configures the default role for interpreted text (single
backticks), avoiding the need to check for / enforce double backticks.
Fixes also one instance in the existing changelog:
- Detect `pytest_` prefixed hooks using the internal plugin manager since
``pluggy`` is deprecating the ``implprefix`` argument to ``PluginManager``.
(`#3487 <https://github.com/pytest-dev/pytest/issues/3487>`_)
