[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 :: 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.1,<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", "filelock" ] [[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 show-source = true exclude = [ ".git", ".tox", ".venv", "tests/roots/*", "build/*", "doc/_build/*", "sphinx/search/*", "doc/usage/extensions/example*.py", ] ignore = [ # pycodestyle "E741", # flake8-builtins "A001", # variable is shadowing a python builtin "A002", # argument is shadowing a python builtin "A003", # class attribute is shadowing a python builtin # flake8-annotations "ANN", # flake8-unused-arguments "ARG001", # unused function argument "ARG002", # unused method argument "ARG003", # unused class method argument "ARG005", # unused lambda argument # flake8-bugbear "B006", # do not use mutable data structures for argument default "B023", # function definition does not bind loop variable "B026", # keyword argument ... must come after starred arguments "B028", # no explicit `stacklevel` keyword argument found # flake8-bugbear opinionated (disabled by default in flake8) "B904", # within an except clause, raise exceptions with `raise ... from ...` # flake8-blind-except "BLE001", # do not catch blind exception # mccabe "C901", # ... is too complex # flake8-commas "COM819", # trailing comma prohibited # pydocstyle "D", # flake8-django "DJ", # Django is not used in Sphinx # flake8-datetimez "DTZ001", # do not use `datetime.datetime()` without `tzinfo` argument "DTZ004", # do not use `datetime.datetime.utcfromtimestamp()` "DTZ005", # do not use `datetime.datetime.now()` without `tz` argument "DTZ006", # do not use `datetime.datetime.fromtimestamp()` without `tz` argument # flake8-errmsg "EM101", # exception must not use a string literal, assign to variable first "EM102", # exception must not use an f-string literal, assign to variable first # eradicate "ERA001", # found commented-out code # flake8-executable "EXE002", # file executable but no shebang present # flake8-boolean-trap "FBT001", # boolean positional arg in function definition "FBT002", # boolean default value in function definition "FBT003", # boolean positional value in function call # flake8-logging-format "G002", # logging statement uses `%` "G003", # logging statement uses `+` # flake8-implicit-str-concat "ISC001", # implicitly concatenated string literals on one line "ISC002", # implicitly concatenated string literals over multiple lines "ISC003", # explicitly concatenated string should be implicitly concatenated # pep8-naming "N", # NumPy-specific rules "NPY", # numpy is not used in Sphinx # pandas-vet "PD", # pandas is not used in Sphinx # pygrep-hooks "PGH003", # flake8-pie "PIE790", # unnecessary 'pass' statement # pylint "PLC1901", # simplify truthy/falsey string comparisons "PLR2004", # avoid magic values "PLR0911", # too many return statements "PLR0912", # too many branches "PLR0913", # too many arguments to function call "PLR0915", # too many statements "PLR5501", # consider using elif to remove an indentation level "PLW0603", # using the global statement to update variables is discouraged "PLW2901", # outer loop variable overwritten by inner assignment # flake8-pytest-style "PT003", # `scope='function'` is implied in `@pytest.fixture()` "PT006", # wrong name type in `@pytest.mark.parametrize`, "PT007", # wrong values type in `@pytest.mark.parametrize` "PT011", # `pytest.raises(ValueError)` is too broad, set the `match` parameter # flake8-use-pathlib "PTH", # flake8-quotes "Q000", # double quotes found but single quotes preferred "Q001", # single quote docstring found but double quotes preferred # flake8-return "RET504", # unnecessary variable assignment before `return` statement "RET505", # unnecessary `else` after `return` statement # flake8-raise "RSE102", # Ruff-specific rules "RUF001", # string contains ambiguous unicode character "RUF003", # comment contains ambiguous unicode character "RUF005", # consider unpacking instead of concatenation # flake8-bandit "S101", # assert used "S105", # possible hardcoded password "S110", # try/except/pass detected "S113", # probable use of requests call without timeout "S301", # 'pickle' unsafe when loading untrusted data "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-self "SLF001", # private member accessed # flake8-print "T201", # print found # flake8-type-checking "TCH001", # move application import into a type-checking block "TCH002", # move third-party import into a type-checking block # tryceratops "TRY", # pyupgrade "UP031", # replace with format specifiers ] external = [ # Whitelist for RUF100 unknown code warnings "E704", "W291", "W293", "SIM110", "SIM113", ] select = [ "ALL", # every check supported by Ruff ] [tool.ruff.per-file-ignores] "doc/conf.py" = ["INP001"] "doc/development/tutorials/examples/*" = ["INP001"] "sphinx/environment/collectors/toctree.py" = ["B026"] "sphinx/environment/adapters/toctree.py" = ["B026"] "tests/*" = ["E501"] [tool.ruff.flake8-quotes] inline-quotes = "single" [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