pyproject.toml

[project]
# https://packaging.python.org/en/latest/specifications/declaring-project-metadata/
name = "documenteer"
description = "Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations."
license = { file = "LICENSE" }
readme = "README.md"
keywords = ["rubin", "lsst"]
# https://pypi.org/classifiers/
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Environment :: Console",
    "Framework :: Sphinx :: Extension",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Natural Language :: English",
    "Operating System :: POSIX",
    "Programming Language :: Python",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Documentation",
    "Topic :: Documentation :: Sphinx",
    "Typing :: Typed",
]
requires-python = ">=3.11"
dynamic = ["version"]
dependencies = [
    "docutils>=0.20",  # solves an extra div bug with the bibliography directive
    "Sphinx>=7",  # Consistent docutils constraint
    "PyYAML",
    "GitPython",
    "requests",
    "click",
    "sphinxcontrib-bibtex>=2.0.0", # for pybtex extension
    "setuptools", # for pkg_resources, used by pybtex
    "pydantic >= 2.0.0",
    "urllib3",
    "pylatexenc",
    "tomlkit",
]

[project.optional-dependencies]
dev = [
    "twine",
    # Documenteer's testing and deployment deps
    "coverage[toml]",
    "pytest",
    "pytest-mock",
    # Test depedendencies for analyzing HTML output
    "lxml",
    "cssselect",
    "defusedxml",  # used by Sphinx but not declared as a dependency
    # Extensions for documenteer's own docs
    "sphinx-click",
    "sphinxcontrib-autoprogram",
    # Type stubs
    "types-setuptools",
    "types-requests",
    "types-PyYAML",
    "types-docutils",
    "types-mock",
    # Testing dependencies
]
guide = [
    # Theme and extensions for Rubin user guide projects
    "autodoc_pydantic",
    "sphinx_design",
    "pydata-sphinx-theme>=0.10.0,<0.13.0",
    "sphinx-autodoc-typehints",
    "sphinx-automodapi",
    "sphinx-copybutton",
    "sphinx-prompt",
    "sphinx-jinja>=2", # namespace changed in 2.0
    "myst-parser",
    "myst-nb",
    "markdown-it-py[linkify]",
    "sphinxcontrib-mermaid>=1",
    "sphinxext-opengraph",
    "sphinxcontrib-redoc",
    "sphinxcontrib-jquery",
    "sphinxext-rediraffe",
    "sphinxcontrib-youtube"
]
technote = [
    # Theme and extensions for technotes
    "technote>=0.9.0,<0.10.0",
    "sphinx-prompt",
    "sphinxcontrib-mermaid",
    "sphinx-diagrams",
    "sphinx_design",
    "myst-nb",
    "sphinxcontrib-youtube"
]

[project.urls]
Homepage = "https://documenteer.lsst.io"
Source = "https://github.com/lsst-sqre/documenteer"

[project.scripts]
documenteer = "documenteer.cli:main"

[build-system]
requires = ["setuptools>=61", "wheel", "setuptools_scm[toml]>=6.2"]
build-backend = 'setuptools.build_meta'

[tool.setuptools_scm]

[tool.black]
# Black configuration is maintained for blacken-docs
line-length = 79
target-version = ['py311']
exclude = '''
/(
    \.eggs
  | \.git
  | \.mypy_cache
  | \.tox
  | \.venv
  | _build
  | build
  | dist
  | node_modules
)/
'''
# Use single-quoted strings so TOML treats the string like a Python r-string
# Multi-line strings are implicitly treated by black as regular expressions

[tool.coverage.run]
parallel = true
branch = true
source = ["documenteer"]

[tool.coverage.paths]
source = ["src", ".tox/*/site-packages"]

[tool.coverage.report]
show_missing = true
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "if self.debug:",
    "if settings.DEBUG",
    "raise AssertionError",
    "raise NotImplementedError",
    "if 0:",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
]

[tool.pytest]
norecursedirs = "node_modules"

[tool.pytest.ini_options]
python_files = ["tests/*.py", "tests/*/*.py"]

[tool.mypy]
disallow_untyped_defs = true
disallow_incomplete_defs = true
ignore_missing_imports = true
local_partial_types = true
no_implicit_reexport = true
show_error_codes = true
strict_equality = true
warn_redundant_casts = true
warn_unreachable = true
warn_unused_ignores = true
plugins = ["pydantic.mypy"]

[tool.ruff]
extend = "ruff-shared.toml"

[tool.ruff.lint]
# Reference for settings: https://beta.ruff.rs/docs/settings/
# Reference for rules: https://beta.ruff.rs/docs/rules/
exclude = ["docs/**", "tests/roots/**", "demo/**"]
extend-ignore = [
   "FIX001", # allow FIXMEs
   "TD001",  # relax formatting for TODOs
   "TD002",  # don't require authors for TODOs
   "TD004",  # don't require colons for TODOs
]

[tool.ruff.lint.extend-per-file-ignores]
"src/documenteer/services/technotemigration.py" = [
    "T201",    # This script can use print
]
"tests/**" = [
    "D103",    # tests don't need docstrings
    "PLR0915", # tests are allowed to be long, sometimes that's convenient
    "PT012",   # way too aggressive about limiting pytest.raises blocks
    "S101",    # tests should use assert
    "SLF001",  # tests are allowed to access private members
    "T201",    # tests can print
    # Temp rules for initial migration
    "PGH003",  # relax having blanket type ignores in tests
    "ANN001",
    "ANN201",
    "ANN202",
    "PT006",
    "PT021",
]
"tests/roots/**" = [
    "INP001",  # These aren't importable packages
]
"src/documenteer/storage/localtemplates/**" = [
    "S701",
    "INP001",
    "D100"
]
"src/documenteer/cli.py" = [
    "T201",  # CLI scripts can print
]

[tool.ruff.lint.isort]
known-first-party = ["documenteer", "tests"]
split-on-trailing-comma = false

[tool.ruff.lint.pep8-naming]
classmethod-decorators = [
    "pydantic.root_validator",  # for pydantic v1
    "pydantic.validator",  # for pydantic v1
]

[tool.scriv]
categories = [
    "Backwards-incompatible changes",
    "New features",
    "Bug fixes",
    "Other changes",
]
entry_title_template = "{{ version }} ({{ date.strftime('%Y-%m-%d') }})"
format = "md"
md_header_level = "2"
new_fragment_template = "file:changelog.d/_template.md.jinja"
skip_fragments = "_template.md.jinja"