Configuration Reference¶
This page documents the configuration extracted from our own pyproject.toml file, demonstrating the power of sphinx-autodoc-toml by dogfooding it!
[build-system]
[project]
Project metadata and configuration.
This section contains the core project metadata including name, version, and dependencies. The project follows semantic versioning.
View Configuration
1name = "sphinx-autodoc-toml"
2version = "0.1.5"
3description = "A Sphinx extension for documenting TOML configuration files with embedded directives"
4readme = "README.md"
5requires-python = ">=3.8"
6license = {file = "LICENSE"}
7authors = [
8 {name = "sphinx-autodoc-toml contributors"}
9]
10classifiers = [
11 "Development Status :: 3 - Alpha",
12 "Framework :: Sphinx :: Extension",
13 "Intended Audience :: Developers",
14 "License :: OSI Approved :: MIT License",
15 "Programming Language :: Python :: 3",
16 "Programming Language :: Python :: 3.8",
17 "Programming Language :: Python :: 3.9",
18 "Programming Language :: Python :: 3.10",
19 "Programming Language :: Python :: 3.11",
20 "Programming Language :: Python :: 3.12",
21 "Topic :: Documentation",
22 "Topic :: Documentation :: Sphinx",
23]
24dependencies = [
25 "sphinx>=5.0",
26 "tomlkit>=0.11.0",
27]
28
29[optional-dependencies]
30dev = [
31 "pytest>=7.0",
32 "pytest-cov>=4.0",
33 "sphinx-needs>=1.0",
34 "types-docutils>=0.20",
35]
36
37#: Command-line tools provided by this package.
38#:
39#: The toml-doc-lint tool validates and formats TOML files according
40#: to the TOML-Doc specification.
41#:
42#: .. spec:: The linter CLI MUST be accessible via the toml-doc-lint command.
43#: :id: S_LINT_006
44#: :status: planned
45#: :links: R_LINT_001
46
47[scripts]
48toml-doc-lint = "sphinx_autodoc_toml.linter:main"
49
50[urls]
51Homepage = "https://github.com/calvingiles/autodoc-toml"
52Repository = "https://github.com/calvingiles/autodoc-toml"
53Issues = "https://github.com/calvingiles/autodoc-toml/issues"
54
55#: Hatch environment configuration.
56#:
57#: Configure hatch to use uv as the installer for all environments.
58#: This provides faster dependency resolution and installation.
59#:
60#: .. spec:: Package installation MUST use uv for improved performance.
61#: :id: S_BUILD_002
62#: :status: implemented
63#: :tags: tooling, performance, developer-experience
64#: :links: R_DX_001, R_DX_002
65#:
66#: .. spec:: Dependencies MUST be locked for reproducible builds across environments.
67#: :id: S_BUILD_005
68#: :status: implemented
69#: :tags: tooling, reproducibility, developer-experience
70#: :links: R_DX_013
71#:
72#: Note: We use uv.lock (via 'uv lock') for dependency locking rather than
73#: hatch-pip-compile. This provides better integration with uv_build backend
74#: and uv's fast resolver, while hatch remains the task runner.
75#: Default environment dependencies and setup scripts.
76#:
77#: .. spec:: A single 'hatch run setup' command MUST configure the complete dev environment.
78#: :id: S_DX_006
79#: :status: implemented
80#: :tags: developer-experience, setup, git-hooks
81#: :links: R_DX_001, R_DX_015
[project.dependencies]
Runtime dependencies required for the extension to function.
The extension requires Sphinx for the documentation framework and tomlkit for parsing TOML files while preserving comments.
View Configuration
1dependencies = [
2 "sphinx>=5.0",
3 "tomlkit>=0.11.0",
4]
[project.optional-dependencies]
Optional development dependencies for testing and documentation.
These dependencies are only needed during development and testing, not for using the extension itself.
View Configuration
1dev = [
2 "pytest>=7.0",
3 "pytest-cov>=4.0",
4 "sphinx-needs>=1.0",
5 "types-docutils>=0.20",
6]
[project.scripts]
Command-line tools provided by this package.
The toml-doc-lint tool validates and formats TOML files according to the TOML-Doc specification.
View Configuration
1toml-doc-lint = "sphinx_autodoc_toml.linter:main"
[tool.hatch.envs.default]
Hatch environment configuration.
Configure hatch to use uv as the installer for all environments. This provides faster dependency resolution and installation.
Note: We use uv.lock (via ‘uv lock’) for dependency locking rather than hatch-pip-compile. This provides better integration with uv_build backend and uv’s fast resolver, while hatch remains the task runner. Default environment dependencies and setup scripts.
Specification: A single 'hatch run setup' command MUST configure the complete dev environment. S_DX_006
|
View Configuration
1installer = "uv"
2dependencies = [
3 "pre-commit>=3.0",
4]
5
6[scripts]
7setup = "pre-commit install"
8
9#: Test environment configuration.
10#:
11#: Environment for running tests with pytest and coverage reporting.
12#:
13#: .. spec:: Test commands MUST provide clear, actionable output.
14#: :id: S_DX_001
15#: :status: implemented
16#: :tags: developer-experience, testing
17#: :links: R_TEST_004, R_DX_003, R_DX_004
[tool.hatch.envs.test]
Test environment configuration.
Environment for running tests with pytest and coverage reporting.
View Configuration
1dependencies = [
2 "pytest>=7.0",
3 "pytest-cov>=4.0",
4 "sphinx-needs>=1.0",
5 "types-docutils>=0.20",
6]
7
8[scripts]
9run = "pytest tests/ -v --cov=src/sphinx_autodoc_toml --cov-report=xml --cov-report=term"
10cov = "pytest tests/ -v --cov=src/sphinx_autodoc_toml --cov-report=html --cov-report=term"
11
12#: Lint environment configuration.
13#:
14#: Environment for running code quality checks with ruff and mypy.
15#:
16#: .. spec:: Linting MUST be runnable via 'hatch run lint:all' command.
17#: :id: S_LINT_002
18#: :status: implemented
19#: :tags: code-quality, tooling, developer-experience
20#: :links: R_DX_005, R_DX_006
21#:
22#: .. spec:: Code formatting MUST be automated and consistent across the project.
23#: :id: S_DX_002
24#: :status: implemented
25#: :tags: developer-experience, code-quality
26#: :links: R_DX_007
[tool.hatch.envs.lint]
Lint environment configuration.
Environment for running code quality checks with ruff and mypy.
View Configuration
1dependencies = [
2 "ruff>=0.1.0",
3 "mypy>=1.0",
4 "types-docutils>=0.20",
5]
6
7[scripts]
8check = "ruff check src/ tests/"
9format-check = "ruff format --check src/ tests/"
10format = "ruff format src/ tests/"
11typing = "mypy src/"
12all = [
13 "check",
14 "format-check",
15 "typing",
16]
17
18#: Documentation environment configuration.
19#:
20#: Environment for building documentation with Sphinx.
21#:
22#: .. spec:: Documentation MUST be buildable via 'hatch run docs:build' command.
23#: :id: S_DOCS_001
24#: :status: implemented
25#: :tags: documentation, tooling, developer-experience
26#: :links: R_DX_008, R_DX_009
27#:
28#: .. spec:: Documentation MUST demonstrate dogfooding by using autodoc-toml for its own config.
29#: :id: S_DX_003
30#: :status: implemented
31#: :tags: developer-experience, documentation
[tool.hatch.envs.docs]
Documentation environment configuration.
Environment for building documentation with Sphinx.
Specification: Documentation MUST demonstrate dogfooding by using autodoc-toml for its own config. S_DX_003
|
View Configuration
1dependencies = [
2 "sphinx>=5.0",
3 "sphinx-needs>=1.0",
4 "myst-parser>=2.0",
5]
6
7[scripts]
8build = "sphinx-build -b html docs docs/_build/html"
9clean = "rm -rf docs/_build"
10
11#: uv_build configuration.
12#:
13#: The uv_build backend automatically handles src-layout packages.
14#: With the src/sphinx_autodoc_toml/ structure, the package is auto-detected.
15#: By default, uv_build includes pyproject.toml, README, LICENSE, and src/ in sdist.
16#: Tests and examples are automatically included following Python packaging conventions.
17#:
18#: .. spec:: Build configuration MUST include tests in source distribution.
19#: :id: S_BUILD_004
20#: :status: implemented
21#: :tags: packaging
22#: :links: R_DX_012
23#:
24#: .. spec:: Package layout MUST follow src-layout convention for clarity.
25#: :id: S_DX_004
26#: :status: implemented
27#: :tags: developer-experience, architecture
28
29#: Pytest test runner configuration.
30#:
31#: Configures how pytest discovers and runs tests.
32#:
33#: .. req:: All tests MUST be located in the tests/ directory.
34#: :id: R_TEST_002
35#: :status: implemented
36#: :tags: testing
[tool.pytest.ini_options]
Pytest test runner configuration.
Configures how pytest discovers and runs tests.
View Configuration
1testpaths = ["tests"]
2python_files = ["test_*.py"]
3python_classes = ["Test*"]
4python_functions = ["test_*"]
[tool.ruff]
Ruff linter configuration.
Ruff is a fast Python linter that checks code style and quality.
View Configuration
1line-length = 100
2target-version = "py38"
3
4[lint]
5select = ["E", "F", "I", "N", "W", "UP"]
6ignore = []
7
8#: Coverage.py configuration for measuring test coverage.
9#:
10#: Specifies which source files to measure and which to omit.
11#:
12#: .. req:: Test coverage MUST be measured and reported.
13#: :id: R_TEST_003
14#: :status: implemented
15#: :links: R_TEST_001
16#: :tags: testing, quality
[tool.ruff.lint]
Ruff linting rules selection.
Enables specific linting rule categories for code quality checks.
View Configuration
1select = ["E", "F", "I", "N", "W", "UP"]
2ignore = []
[tool.coverage.run]
Coverage.py configuration for measuring test coverage.
Specifies which source files to measure and which to omit.
View Configuration
1source = ["src/sphinx_autodoc_toml"]
2omit = [
3 "*/tests/*",
4 "*/test_*.py",
5]
[tool.coverage.report]
Coverage reporting configuration.
Defines which lines to exclude from coverage reports.
View Configuration
1exclude_lines = [
2 "pragma: no cover",
3 "def __repr__",
4 "raise AssertionError",
5 "raise NotImplementedError",
6 "if __name__ == .__main__.:",
7 "if TYPE_CHECKING:",
8 "@abstractmethod",
9]
[tool.mypy]
MyPy static type checker configuration.
MyPy performs static type checking to catch type-related bugs.
View Configuration
1python_version = "3.9"
2warn_return_any = true
3warn_unused_configs = true
4disallow_untyped_defs = true
5
6[[overrides]]
7module = ["sphinx.*", "docutils.*"]
8ignore_missing_imports = true
[[tool.mypy.overrides]
MyPy overrides for third-party libraries without type stubs.
Build system configuration for sphinx-autodoc-toml.
This project uses uv_build as its build backend for significantly faster builds (10-35x faster than hatchling). uv_build is PEP 517-compliant and now stable as of late 2024.
View Configuration