|
1
|
|
|
""" |
|
2
|
|
|
Sphinx config file. |
|
3
|
|
|
|
|
4
|
|
|
Uses several extensions to get API docs and sourcecode. |
|
5
|
|
|
https://www.sphinx-doc.org/en/master/usage/configuration.html |
|
6
|
|
|
""" |
|
7
|
|
|
|
|
8
|
|
|
from pathlib import Path |
|
9
|
|
|
from typing import Optional, Type, TypeVar |
|
10
|
|
|
|
|
11
|
|
|
import tomlkit |
|
12
|
|
|
|
|
13
|
|
|
# This assumes that we have the full project root above, containing pyproject.toml |
|
14
|
|
|
_root = Path(__file__).parent.parent.absolute() |
|
15
|
|
|
_toml = tomlkit.loads((_root / "pyproject.toml").read_text(encoding="utf8")) |
|
16
|
|
|
|
|
17
|
|
|
T = TypeVar("T") |
|
18
|
|
|
|
|
19
|
|
|
|
|
20
|
|
|
def find(key: str, default: Optional[T] = None, as_type: Type[T] = str) -> Optional[T]: |
|
21
|
|
|
""" |
|
22
|
|
|
Gets a value from pyproject.toml, or a default. |
|
23
|
|
|
|
|
24
|
|
|
Args: |
|
25
|
|
|
key: A period-delimited TOML key; e.g. ``tools.poetry.name`` |
|
26
|
|
|
default: Default value if any node in the key is not found |
|
27
|
|
|
as_type: Convert non-``None`` values to this type before returning |
|
28
|
|
|
|
|
29
|
|
|
Returns: |
|
30
|
|
|
The value converted to ``as_type``, or ``default`` if it was not found |
|
31
|
|
|
""" |
|
32
|
|
|
at = _toml |
|
33
|
|
|
for k in key.split("."): |
|
34
|
|
|
at = at.get(k) |
|
35
|
|
|
if at is None: |
|
36
|
|
|
return default |
|
37
|
|
|
return as_type(at) |
|
38
|
|
|
|
|
39
|
|
|
|
|
40
|
|
|
# Basic information, used by Sphinx |
|
41
|
|
|
# Leave language as None unless you have multiple translations |
|
42
|
|
|
language = None |
|
43
|
|
|
project = find("tool.poetry.name") |
|
44
|
|
|
version = find("tool.poetry.version") |
|
45
|
|
|
release = version |
|
46
|
|
|
author = ", ".join(find("tool.poetry.authors", as_type=list)) |
|
47
|
|
|
language = "en" |
|
48
|
|
|
|
|
49
|
|
|
# Copyright string (for documentation) |
|
50
|
|
|
# It's not clear whether we're supposed to, but we'll add the license |
|
51
|
|
|
copyright = find("tool.tyrannosaurus.sources.copyright") |
|
52
|
|
|
_license = find("tool.tyrannosaurus.sources.doc_license") |
|
53
|
|
|
_license_url = find("tool.tyrannosaurus.sources.doc_license_url") |
|
54
|
|
|
|
|
55
|
|
|
# Load extensions |
|
56
|
|
|
# These should be in docs/requirements.txt |
|
57
|
|
|
# Napoleon is bundled in Sphinx, so we don't need to list it there |
|
58
|
|
|
# NOTE: 'autoapi' here refers to sphinx-autoapi |
|
59
|
|
|
# See https://sphinx-autoapi.readthedocs.io/ |
|
60
|
|
|
extensions = [ |
|
61
|
|
|
"autoapi.extension", |
|
62
|
|
|
"sphinx.ext.napoleon", |
|
63
|
|
|
"sphinx_copybutton", |
|
64
|
|
|
"sphinx_rtd_theme", |
|
65
|
|
|
] |
|
66
|
|
|
master_doc = "index" |
|
67
|
|
|
napoleon_include_special_with_doc = True |
|
68
|
|
|
autoapi_type = "python" |
|
69
|
|
|
autoapi_dirs = [str(_root / project)] |
|
70
|
|
|
autoapi_keep_files = True |
|
71
|
|
|
autoapi_python_class_content = "both" |
|
72
|
|
|
autoapi_member_order = "groupwise" |
|
73
|
|
|
autoapi_options = ["private-members", "undoc-members", "special-members"] |
|
74
|
|
|
|
|
75
|
|
|
# The vast majority of Sphinx themes are unmaintained |
|
76
|
|
|
# This includes the commonly used alabaster theme |
|
77
|
|
|
# The readthedocs theme is pretty good anyway |
|
78
|
|
|
# These can be specific to the theme, or processed by Sphinx directly |
|
79
|
|
|
# https://www.sphinx-doc.org/en/master/usage/configuration.html |
|
80
|
|
|
html_theme = "sphinx_rtd_theme" |
|
81
|
|
|
html_theme_options = { |
|
82
|
|
|
"collapse_navigation": False, |
|
83
|
|
|
"navigation_depth": False, |
|
84
|
|
|
"style_external_links": True, |
|
85
|
|
|
} |
|
86
|
|
|
|
|
87
|
|
|
# doc types to build |
|
88
|
|
|
sphinx_enable_epub_build = False |
|
89
|
|
|
sphinx_enable_pdf_build = False |
|
90
|
|
|
exclude_patterns = ["_build", "Thumbs.db", ".*", "~*", "*~", "*#"] |
|
91
|
|
|
|
|
92
|
|
|
|
|
93
|
|
|
if __name__ == "__main__": |
|
94
|
|
|
print(f"{project} v{version}\n© Copyright {copyright}") |
|
95
|
|
|
|
dmyersturnbull /
tyrannosaurus
