pyproject.toml

[build-system]
requires = ["flit_core>=3.7"]
build-backend = "flit_core.buildapi"

# project metadata
[project]
name = "Sphinx"
description = "Python documentation generator"
readme = "README.rst"
urls.Changelog = "https://www.sphinx-doc.org/en/master/changes.html"
urls.Code = "https://github.com/sphinx-doc/sphinx"
urls.Download = "https://pypi.org/project/Sphinx/"
urls.Homepage = "https://www.sphinx-doc.org/"
urls."Issue tracker" = "https://github.com/sphinx-doc/sphinx/issues"
license.text = "BSD-2-Clause"
requires-python = ">=3.8"

# Classifiers list: https://pypi.org/classifiers/
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Environment :: Console",
    "Environment :: Web Environment",
    "Intended Audience :: Developers",
    "Intended Audience :: Education",
    "Intended Audience :: End Users/Desktop",
    "Intended Audience :: Science/Research",
    "Intended Audience :: System Administrators",
    "License :: OSI Approved :: BSD License",
    "Operating System :: OS Independent",
    "Programming Language :: Python",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: Implementation :: CPython",
    "Programming Language :: Python :: Implementation :: PyPy",
    "Framework :: Setuptools Plugin",
    "Framework :: Sphinx",
    "Framework :: Sphinx :: Extension",
    "Framework :: Sphinx :: Theme",
    "Topic :: Documentation",
    "Topic :: Documentation :: Sphinx",
    "Topic :: Internet :: WWW/HTTP :: Site Management",
    "Topic :: Printing",
    "Topic :: Software Development",
    "Topic :: Software Development :: Documentation",
    "Topic :: Text Processing",
    "Topic :: Text Processing :: General",
    "Topic :: Text Processing :: Indexing",
    "Topic :: Text Processing :: Markup",
    "Topic :: Text Processing :: Markup :: HTML",
    "Topic :: Text Processing :: Markup :: LaTeX",
    "Topic :: Utilities",
]
dependencies = [
    "sphinxcontrib-applehelp",
    "sphinxcontrib-devhelp",
    "sphinxcontrib-jsmath",
    "sphinxcontrib-htmlhelp>=2.0.0",
    "sphinxcontrib-serializinghtml>=1.1.5",
    "sphinxcontrib-qthelp",
    "Jinja2>=3.0",
    "Pygments>=2.13",
    "docutils>=0.18,<0.20",
    "snowballstemmer>=2.0",
    "babel>=2.9",
    "alabaster>=0.7,<0.8",
    "imagesize>=1.3",
    "requests>=2.25.0",
    "packaging>=21.0",
    "importlib-metadata>=4.8; python_version < '3.10'",
    "colorama>=0.4.5; sys_platform == 'win32'",
]
dynamic = ["version"]

[project.optional-dependencies]
docs = [
    "sphinxcontrib-websupport",
]
lint = [
    "flake8>=3.5.0",
    "flake8-simplify",
    "isort",
    "ruff",
    "mypy>=0.990",
    "sphinx-lint",
    "docutils-stubs",
    "types-requests",
]
test = [
    "pytest>=4.6",
    "html5lib",
    "cython",
]

[[project.authors]]
name = "Georg Brandl"
email = "georg@python.org"

[project.scripts]
sphinx-build = "sphinx.cmd.build:main"
sphinx-quickstart = "sphinx.cmd.quickstart:main"
sphinx-apidoc = "sphinx.ext.apidoc:main"
sphinx-autogen = "sphinx.ext.autosummary.generate:main"

[project.entry-points."distutils.commands"]
build_sphinx = 'sphinx.setup_command:BuildDoc'

[tool.flit.module]
name = "sphinx"

[tool.flit.sdist]
include = [
    "LICENSE",
    "AUTHORS",
    "CHANGES",
    # Documentation
    "doc/",
    "CODE_OF_CONDUCT",  # used as an include in the Documentation
    "EXAMPLES",  # used as an include in the Documentation
    # Tests
    "tests/",
    "tox.ini",
    # Utilities
    "utils/",
    "babel.cfg",
]
exclude = [
    "doc/_build",
]

[tool.isort]
line_length = 95
profile = "black"
remove_redundant_aliases = true

[tool.ruff]
target-version = "py38"  # Pin Ruff to Python 3.8
line-length = 95
exclude = [
    '.git',
    '.tox',
    '.venv',
    'tests/roots/*',
    'build/*',
    'doc/_build/*',
    'sphinx/search/*',
    'doc/usage/extensions/example*.py',
]
ignore = [
    # pycodestyle
    'E741',
    # flake8-bugbear
    'B006',
    'B023',
    # flake8-bugbear opinionated (disabled by default in flake8)
    'B904',
    'B905',
    # flake8-executable
    "EXE002",  # file executable but no shebang present
    # pygrep-hooks
    "PGH003",
    # flake8-pie
    "PIE790",   # unnecessary 'pass' statement
    # pylint
    "PLR2004",  # avoid magic values
    "PLR0913",  # too many arguments to function call
    # flake8-bandit
    "S101",  # assert used
    "S105",  # possible hardcoded password
    "S110",  # try/except/pass detected
    "S113",  # probable use of requests call without timeout
    "S324",  # probable use of insecure hash functions
    "S701",  # use autoescape=True for Jinja
    # flake8-simplify
    "SIM102", # nested 'if' statements
    "SIM103", # return condition directly
    "SIM105", # use contextlib.suppress
    "SIM108", # use ternary operator
    "SIM115", # use context handler for opening files
    "SIM117", # use single 'with' statement
    # flake8-type-checking
    "TCH001", # move application import into a type-checking block
    "TCH002", # move third-party import into a type-checking block
    # pyupgrade
    "UP031", # replace with format specifiers
]
external = [  # Whitelist for RUF100 unkown code warnings
    "E704",
    "W291",
    "W293",
    "SIM110",
    "SIM113",
]
select = [
    "E",   # pycodestyle
    "F",   # Pyflakes
    "W",   # pycodestyle
    # plugins:
    "B",   # flake8-bugbear
    "C4",  # flake8-comprehensions
    "EXE", # flake8-executable
    "I",   # isort
    "ICN", # flake8-import-conventions
    "INP", # flake8-no-pep420
    "PGH", # pygrep-hooks
    "PIE", # flake8-pie
    "PL",  # pylint
    "S",   # flake8-bandit
    "SIM", # flake8-simplify
    "T10", # flake8-debugger
    "TCH", # flake8-type-checking
    "TID", # flake8-tidy-imports
    "UP",  # pyupgrade
    "YTT", # flake8-2020
    "RUF100",  # yesqa
]

[tool.ruff.per-file-ignores]
"doc/conf.py" = ["INP001"]
"doc/development/tutorials/examples/*" = ["INP001"]

"tests/*" = ["E501"]
"sphinx/environment/collectors/toctree.py" = ["B026"]
"sphinx/environment/adapters/toctree.py" = ["B026"]

[tool.mypy]
check_untyped_defs = true
disallow_incomplete_defs = true
follow_imports = "skip"
ignore_missing_imports = true
no_implicit_optional = true
python_version = "3.8"
show_column_numbers = true
show_error_codes = true
show_error_context = true
strict_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
disallow_any_generics = true

[[tool.mypy.overrides]]
module = [
    "sphinx.application",
    "sphinx.builders",
    "sphinx.builders.html",
    "sphinx.builders.latex",
    "sphinx.builders.linkcheck",
    "sphinx.domains",
    "sphinx.domains.c",
    "sphinx.domains.cpp",
    "sphinx.domains.javascript",
    "sphinx.domains.python",
    "sphinx.domains.std",
    "sphinx.environment",
    "sphinx.environment.adapters.toctree",
    "sphinx.environment.adapters.indexentries",
    "sphinx.ext.apidoc",
    "sphinx.ext.autodoc",
    "sphinx.ext.autodoc.mock",
    "sphinx.ext.autodoc.importer",
    "sphinx.ext.autodoc.preserve_defaults",
    "sphinx.ext.autodoc.type_comment",
    "sphinx.ext.autosummary",
    "sphinx.ext.autosummary.generate",
    "sphinx.ext.doctest",
    "sphinx.ext.duration",
    "sphinx.ext.graphviz",
    "sphinx.ext.inheritance_diagram",
    "sphinx.ext.intersphinx",
    "sphinx.ext.imgmath",
    "sphinx.ext.linkcode",
    "sphinx.ext.mathjax",
    "sphinx.ext.napoleon",
    "sphinx.ext.napoleon.docstring",
    "sphinx.pycode.parser",
    "sphinx.registry",
    "sphinx.setup_command",
    "sphinx.testing.util",
    "sphinx.transforms.i18n",
    "sphinx.transforms.post_transforms.images",
    "sphinx.util.cfamily",
    "sphinx.util.docfields",
    "sphinx.util.docutils",
    "sphinx.util.typing",
    "sphinx.writers.latex",
    "sphinx.writers.text",
    "sphinx.writers.xml",
]
strict_optional = false

[[tool.mypy.overrides]]
module = [
    "sphinx.application",
    "sphinx.builders._epub_base",
    "sphinx.builders.html",
    "sphinx.builders.linkcheck",
    "sphinx.cmd.quickstart",
    "sphinx.config",
    "sphinx.domains",
    "sphinx.domains.c",
    "sphinx.domains.cpp",
    "sphinx.environment.*",
    "sphinx.events",
    "sphinx.ext.*",
    "sphinx.highlighting",
    "sphinx.jinja2glue",
    "sphinx.registry",
    "sphinx.roles",
    "sphinx.search.*",
    "sphinx.testing.*",
    "sphinx.util.*",
]
disallow_any_generics = false

[tool.pytest.ini_options]
filterwarnings = [
    "all",
    "ignore::DeprecationWarning:docutils.io",
    "ignore::DeprecationWarning:pyximport.pyximport",
    "ignore::ImportWarning:importlib._bootstrap",
]
markers = [
    "apidoc",
    "setup_command",
]
testpaths = ["tests"]

[tool.coverage.run]
branch = true
parallel = true
source = ['sphinx']

[tool.coverage.report]
exclude_lines = [
    # Have to re-enable the standard pragma
    'pragma: no cover',
    # Don't complain if tests don't hit defensive assertion code:
    'raise NotImplementedError',
    # Don't complain if non-runnable code isn't run:
    'if __name__ == .__main__.:',
]
ignore_errors = true