- pytest is a mature full-featured Python testing tool that helps
- you write better programs.
-
diff --git a/doc/en/_templates/style.html b/doc/en/_templates/style.html
deleted file mode 100644
index 400cb75ff97..00000000000
--- a/doc/en/_templates/style.html
+++ /dev/null
@@ -1,7 +0,0 @@
-
diff --git a/doc/en/conf.py b/doc/en/conf.py
index 0d440ec448a..9558a75f927 100644
--- a/doc/en/conf.py
+++ b/doc/en/conf.py
@@ -1,20 +1,3 @@
-#
-# pytest documentation build configuration file, created by
-# sphinx-quickstart on Fri Oct 8 17:54:28 2010.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The full version, including alpha/beta/rc tags.
-# The short X.Y version.
from __future__ import annotations
import os
@@ -23,61 +6,26 @@
from textwrap import dedent
from typing import TYPE_CHECKING
-from _pytest import __version__ as full_version
+from pytest import __version__ as full_version
-version = full_version.split("+")[0]
-
if TYPE_CHECKING:
import sphinx.application
-
PROJECT_ROOT_DIR = Path(__file__).parents[2].resolve()
-IS_RELEASE_ON_RTD = (
- os.getenv("READTHEDOCS", "False") == "True"
- and os.environ["READTHEDOCS_VERSION_TYPE"] == "tag"
-)
-if IS_RELEASE_ON_RTD:
- tags: set[str]
- # pylint: disable-next=used-before-assignment
- tags.add("is_release") # noqa: F821
-
-release = ".".join(version.split(".")[:2])
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
-
-autodoc_member_order = "bysource"
-autodoc_typehints = "description"
-autodoc_typehints_description_target = "documented"
-todo_include_todos = 1
-
-latex_engine = "lualatex"
-
-latex_elements = {
- "preamble": dedent(
- r"""
- \directlua{
- luaotfload.add_fallback("fallbacks", {
- "Noto Serif CJK SC:style=Regular;",
- "Symbola:Style=Regular;"
- })
- }
- \setmainfont{FreeSerif}[RawFeature={fallback=fallbacks}]
- """
- )
-}
+# -- Project information ---------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-# -- General configuration -----------------------------------------------------
+project = "pytest"
+copyright = "2015, holger krekel and pytest-dev team"
+version = full_version.split("+")[0]
+release = ".".join(version.split(".")[:2])
-# If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.0'
+# -- General configuration -------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+root_doc = "index"
extensions = [
"pygments_pytest",
"sphinx.ext.autodoc",
@@ -98,35 +46,6 @@
if shutil.which("inkscape"):
extensions.append("sphinxcontrib.inkscapeconverter")
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# The suffix of source filenames.
-source_suffix = ".rst"
-
-# The encoding of source files.
-# source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = "contents"
-
-# General information about the project.
-project = "pytest"
-copyright = "2015, holger krekel and pytest-dev team"
-
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-# language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-# today = ''
-# Else, today_fmt is used as the format for a strftime call.
-# today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
exclude_patterns = [
"_build",
"naming20.rst",
@@ -138,38 +57,9 @@
"setup.rst",
"example/remoteinterp.rst",
]
-
-
-# The reST default role (used for this markup: `text`) to use for all documents.
+templates_path = ["_templates"]
default_role = "literal"
-# If true, '()' will be appended to :func: etc. cross-reference text.
-# add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-add_module_names = False
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-# show_authors = False
-
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-# A list of regular expressions that match URIs that should not be checked when
-# doing a linkcheck.
-linkcheck_ignore = [
- "https://blogs.msdn.microsoft.com/bharry/2017/06/28/testing-in-a-cloud-delivery-cadence/",
- "http://pythontesting.net/framework/pytest-introduction/",
- r"https://github.com/pytest-dev/pytest/issues/\d+",
- r"https://github.com/pytest-dev/pytest/pull/\d+",
-]
-
-# The number of worker threads to use when checking links (default=5).
-linkcheck_workers = 5
-
-
nitpicky = True
nitpick_ignore = [
# TODO (fix in pluggy?)
@@ -217,126 +107,91 @@
("py:class", "_ScopeName"),
]
+add_module_names = False
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages. See the documentation for
-# a list of builtin themes.
-html_theme = "furo"
+# -- Options for Autodoc --------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-# html_theme_options = {"index_logo": None}
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented"
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
+# -- Options for intersphinx ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
-# The name for this set of Sphinx documents. If None, it defaults to
-# " v documentation".
-html_title = "pytest documentation"
+intersphinx_mapping = {
+ "pluggy": ("https://pluggy.readthedocs.io/en/stable", None),
+ "python": ("https://docs.python.org/3", None),
+ "numpy": ("https://numpy.org/doc/stable", None),
+ "pip": ("https://pip.pypa.io/en/stable", None),
+ "tox": ("https://tox.wiki/en/stable", None),
+ "virtualenv": ("https://virtualenv.pypa.io/en/stable", None),
+ "setuptools": ("https://setuptools.pypa.io/en/stable", None),
+ "packaging": ("https://packaging.python.org/en/latest", None),
+}
-# A shorter title for the navigation bar. Default is the same as html_title.
-html_short_title = f"pytest-{release}"
+# -- Options for todo -----------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-html_logo = "img/pytest_logo_curves.svg"
+todo_include_todos = True
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-html_favicon = "img/favicon.png"
+# -- Options for linkcheck builder ----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
-# html_sidebars = {'index': 'indexsidebar.html'}
-
-html_sidebars = {
- "index": [
- "sidebar/brand.html",
- "sidebar/search.html",
- "sidebar/scroll-start.html",
- "sidebarintro.html",
- "globaltoc.html",
- "links.html",
- "sidebar/scroll-end.html",
- "style.html",
- ],
- "**": [
- "sidebar/brand.html",
- "sidebar/search.html",
- "sidebar/scroll-start.html",
- "globaltoc.html",
- "relations.html",
- "links.html",
- "sidebar/scroll-end.html",
- "style.html",
- ],
-}
+linkcheck_ignore = [
+ "https://blogs.msdn.microsoft.com/bharry/2017/06/28/testing-in-a-cloud-delivery-cadence/",
+ "http://pythontesting.net/framework/pytest-introduction/",
+ r"https://github.com/pytest-dev/pytest/issues/\d+",
+ r"https://github.com/pytest-dev/pytest/pull/\d+",
+]
+linkcheck_workers = 5
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-# html_additional_pages = {}
-# html_additional_pages = {'index': 'index.html'}
+# -- Options for HTML output ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_theme = "furo"
+html_theme_options = {"sidebar_hide_name": True}
-# If false, no module index is generated.
-html_domain_indices = True
+html_static_path = ["_static"]
+html_css_files = [
+ "pytest-custom.css",
+]
-# If false, no index is generated.
-html_use_index = False
+html_title = "pytest documentation"
+html_short_title = f"pytest-{release}"
-# If true, the index is split into individual pages for each letter.
-# html_split_index = False
+html_logo = "_static/pytest1.png"
+html_favicon = "img/favicon.png"
-# If true, links to the reST sources are added to the pages.
+html_use_index = False
html_show_sourcelink = False
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-# html_show_sphinx = True
+html_baseurl = "https://docs.pytest.org/en/stable/"
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-# html_show_copyright = True
+# -- Options for HTML Help output -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a tag referring to it. The value of this option must be the
-# base URL from which the finished HTML is served.
-# html_use_opensearch = ''
+htmlhelp_basename = "pytestdoc"
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = None
-# Output file base name for HTML help builder.
-htmlhelp_basename = "pytestdoc"
+# -- Options for manual page output ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-manual-page-output
-# The base URL which points to the root of the HTML documentation. It is used
-# to indicate the location of document using the canonical link relation (#12363).
-html_baseurl = "https://docs.pytest.org/en/stable/"
+man_pages = [
+ ("how-to/usage", "pytest", "pytest usage", ["holger krekel at merlinux eu"], 1)
+]
-# -- Options for LaTeX output --------------------------------------------------
+# -- Options for epub output ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output
-# The paper size ('letter' or 'a4').
-# latex_paper_size = 'letter'
+epub_title = "pytest"
+epub_author = "holger krekel at merlinux eu"
+epub_publisher = "holger krekel at merlinux eu"
+epub_copyright = "2013, holger krekel et alii"
-# The font size ('10pt', '11pt' or '12pt').
-# latex_font_size = '10pt'
+# -- Options for LaTeX output --------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
(
"contents",
@@ -346,80 +201,29 @@
"manual",
)
]
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-# latex_show_urls = False
-
-# Additional stuff for the LaTeX preamble.
-# latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
latex_domain_indices = False
+latex_engine = "lualatex"
+latex_elements = {
+ "preamble": dedent(
+ r"""
+ \directlua{
+ luaotfload.add_fallback("fallbacks", {
+ "Noto Serif CJK SC:style=Regular;",
+ "Symbola:Style=Regular;"
+ })
+ }
-# -- Options for manual page output --------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
- ("how-to/usage", "pytest", "pytest usage", ["holger krekel at merlinux eu"], 1)
-]
-
-
-# -- Options for Epub output ---------------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = "pytest"
-epub_author = "holger krekel at merlinux eu"
-epub_publisher = "holger krekel at merlinux eu"
-epub_copyright = "2013, holger krekel et alii"
-
-# The language of the text. It defaults to the language option
-# or en if the language is not set.
-# epub_language = ''
-
-# The scheme of the identifier. Typical schemes are ISBN or URL.
-# epub_scheme = ''
-
-# The unique identifier of the text. This can be an ISBN number
-# or the project homepage.
-# epub_identifier = ''
-
-# A unique identification for the text.
-# epub_uid = ''
-
-# HTML files that should be inserted before the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-# epub_pre_files = []
-
-# HTML files that should be inserted after the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-# epub_post_files = []
-
-# A list of files that should not be packed into the epub file.
-# epub_exclude_files = []
-
-# The depth of the table of contents in toc.ncx.
-# epub_tocdepth = 3
-
-# Allow duplicate toc entries.
-# epub_tocdup = True
-
+ \setmainfont{FreeSerif}[RawFeature={fallback=fallbacks}]
+ """
+ )
+}
-# -- Options for texinfo output ------------------------------------------------
+# -- Options for texinfo output -------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-texinfo-output
texinfo_documents = [
(
- master_doc,
+ root_doc,
"pytest",
"pytest Documentation",
(
@@ -433,29 +237,34 @@
)
]
-# -- Options for towncrier_draft extension -----------------------------------
+# -- Options for towncrier_draft extension --------------------------------------------
+# https://sphinxcontrib-towncrier.readthedocs.io/en/latest/#how-to-use-this
towncrier_draft_autoversion_mode = "draft" # or: 'sphinx-version', 'sphinx-release'
towncrier_draft_include_empty = True
towncrier_draft_working_directory = PROJECT_ROOT_DIR
towncrier_draft_config_path = "pyproject.toml" # relative to cwd
-
# -- Options for sphinx_issues extension -----------------------------------
+# https://github.com/sloria/sphinx-issues#installation-and-configuration
issues_github_path = "pytest-dev/pytest"
+# -- Custom Read the Docs build configuration -----------------------------------------
+# https://docs.readthedocs.io/en/stable/reference/environment-variables.html#environment-variable-reference
+# https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#including-content-based-on-tags
-intersphinx_mapping = {
- "pluggy": ("https://pluggy.readthedocs.io/en/stable", None),
- "python": ("https://docs.python.org/3", None),
- "numpy": ("https://numpy.org/doc/stable", None),
- "pip": ("https://pip.pypa.io/en/stable", None),
- "tox": ("https://tox.wiki/en/stable", None),
- "virtualenv": ("https://virtualenv.pypa.io/en/stable", None),
- "setuptools": ("https://setuptools.pypa.io/en/stable", None),
- "packaging": ("https://packaging.python.org/en/latest", None),
-}
+IS_RELEASE_ON_RTD = (
+ os.getenv("READTHEDOCS", "False") == "True"
+ and os.environ["READTHEDOCS_VERSION_TYPE"] == "tag"
+)
+if IS_RELEASE_ON_RTD:
+ tags: set[str]
+ # pylint: disable-next=used-before-assignment
+ tags.add("is_release") # noqa: F821
+
+# -- Custom documentation plugin ------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/development/tutorials/extending_syntax.html#the-setup-function
def setup(app: sphinx.application.Sphinx) -> None:
diff --git a/doc/en/contents.rst b/doc/en/contents.rst
index 181207203b2..07c0b3ff6b9 100644
--- a/doc/en/contents.rst
+++ b/doc/en/contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
.. _toc:
Full pytest documentation
diff --git a/doc/en/index.rst b/doc/en/index.rst
index 8de3b3993dd..a907d1ff549 100644
--- a/doc/en/index.rst
+++ b/doc/en/index.rst
@@ -1,5 +1,3 @@
-:orphan:
-
.. _features:
.. sidebar:: **Next Open Trainings and Events**
@@ -13,6 +11,36 @@
pytest: helps you write better programs
=======================================
+.. toctree::
+ :hidden:
+
+ getting-started
+ how-to/index
+ reference/index
+ explanation/index
+ example/index
+
+.. toctree::
+ :caption: About the project
+ :hidden:
+
+ changelog
+ contributing
+ backwards-compatibility
+ sponsor
+ tidelift
+ license
+ contact
+
+.. toctree::
+ :caption: Useful links
+ :hidden:
+
+ pytest @ PyPI
+ pytest @ GitHub
+ Issue Tracker
+ PDF Documentation
+
.. module:: pytest
The ``pytest`` framework makes it easy to write small, readable tests, and can
 }})
-