|
4 | 4 | This file only contains a selection of the most common options. |
5 | 5 |
|
6 | 6 | For a full list see the documentation: |
7 | | - http://www.sphinx-doc.org/en/master/config |
| 7 | + https://www.sphinx-doc.org/en/master/config |
8 | 8 | """ |
9 | 9 | from __future__ import absolute_import, print_function, unicode_literals |
10 | 10 |
|
11 | 11 | import os |
| 12 | +import runpy |
12 | 13 | import sys |
13 | 14 | import time |
14 | 15 |
|
| 16 | +from setuptools import find_packages |
| 17 | + |
15 | 18 | # -- Path setup ----------------------------------------------------- |
16 | 19 | # If extensions (or modules to document with autodoc) are in another |
17 | 20 | # directory, add these directories to sys.path here. If the directory |
18 | 21 | # is relative to the documentation root, use os.path.abspath to make |
19 | 22 | # it absolute, like shown here. |
20 | | -sys.path.insert(0, os.path.abspath(__file__)) |
21 | 23 |
|
22 | | -from skeleton.__version__ import ( |
23 | | - __author__, |
24 | | - __title__, |
25 | | - __version__, |
26 | | - __description__ |
27 | | -) # noqa |
| 24 | +project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../")) |
| 25 | + |
| 26 | +sys.path.insert(0, os.path.abspath(__file__)) |
| 27 | +sys.path.insert(0, project_root) |
| 28 | + |
| 29 | + |
| 30 | +def module_name(exclude=("docs*", "examples*", "scripts*", "tests*", "build*", "venv*"), |
| 31 | + where=".", include=("*",), default=None): |
| 32 | + """Infer the top-level module name for the current project. |
| 33 | +
|
| 34 | + Returns: |
| 35 | + str: First matching module name, or `default` if none found. |
| 36 | + """ |
| 37 | + packages = find_packages(where=where, include=include, exclude=exclude) |
| 38 | + return next(iter(sorted(packages)), default) |
| 39 | + |
| 40 | + |
| 41 | +def load_metadata_from_version_file(root=None, module=None): |
| 42 | + """Loads metadata from a __version__.py file somewhere under the project root. |
| 43 | +
|
| 44 | + Args: |
| 45 | + root (str): Path to the root of the project. If None, the current directory is used. |
| 46 | + module (str): Name of the module to load. If None, the first found module is used. |
| 47 | +
|
| 48 | + Returns: |
| 49 | + dict: { |
| 50 | + '__title__': str, |
| 51 | + '__author__': str, |
| 52 | + '__version__': str, |
| 53 | + '__description__': str |
| 54 | + } |
| 55 | + """ |
| 56 | + if root is None: |
| 57 | + root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../")) |
| 58 | + |
| 59 | + if module is None: |
| 60 | + module = module_name(where=root) |
| 61 | + |
| 62 | + version_file = os.path.join(root, module, "__version__.py") |
| 63 | + |
| 64 | + if not os.path.isfile(version_file): |
| 65 | + # Search for any __version__.py |
| 66 | + for root, dirs, files in os.walk(root): |
| 67 | + if "__version__.py" in files: |
| 68 | + version_file = os.path.join(root, "__version__.py") |
| 69 | + break |
| 70 | + else: |
| 71 | + raise FileNotFoundError("Could not locate __version__.py in project.") |
| 72 | + |
| 73 | + metadata = runpy.run_path(version_file) |
| 74 | + return { |
| 75 | + "__title__": metadata.get("__title__", os.path.basename(root)), |
| 76 | + "__author__": metadata.get("__author__", "Unknown"), |
| 77 | + "__version__": metadata.get("__version__", "0.0.0"), |
| 78 | + "__description__": metadata.get("__description__", ""), |
| 79 | + } |
| 80 | + |
| 81 | + |
| 82 | +__meta__ = load_metadata_from_version_file(root=project_root) |
| 83 | +__title__ = __meta__["__title__"] |
| 84 | +__author__ = __meta__["__author__"] |
| 85 | +__version__ = __meta__["__version__"] |
| 86 | +__description__ = __meta__["__description__"] |
28 | 87 |
|
29 | 88 | # -- Project information -------------------------------------------- |
30 | 89 |
|
|
33 | 92 | # noinspection PyShadowingBuiltins |
34 | 93 | copyright = "{0}, {1}".format(author, time.strftime("%Y")) |
35 | 94 | version = "{0}.".format(__version__.split(".")[:-1]) # Short X.Y version. |
36 | | -release = __version__ # Full version, including alpha/beta/rc tags |
| 95 | +release = __version__ # full version, including alpha/beta/rc tags |
37 | 96 |
|
38 | 97 | # -- General configuration ------------------------------------------ |
39 | 98 |
|
|
47 | 106 | # https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html |
48 | 107 | # https://www.sphinx-doc.org/en/master/usage/extensions/todo.html |
49 | 108 | extensions = [ |
50 | | - "sphinx.ext.autodoc", |
51 | | - "sphinx.ext.viewcode", |
52 | | - "sphinx.ext.todo", |
53 | | - "sphinxcontrib.napoleon", |
54 | | - "guzzle_sphinx_theme" |
| 109 | + "sphinx.ext.autodoc", |
| 110 | + "sphinx.ext.viewcode", |
| 111 | + "sphinx.ext.todo", |
| 112 | + "sphinx.ext.napoleon", |
| 113 | + "guzzle_sphinx_theme" |
55 | 114 | ] |
56 | 115 |
|
57 | 116 | intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} |
|
93 | 152 |
|
94 | 153 | # Custom sidebar templates, filenames relative to this file. |
95 | 154 | html_sidebars = { |
96 | | - "**": [ |
97 | | - "logo-text.html", |
98 | | - "globaltoc.html", |
99 | | - "localtoc.html", |
100 | | - "searchbox.html" |
101 | | - ] |
| 155 | + "**": [ |
| 156 | + "logo-text.html", |
| 157 | + "globaltoc.html", |
| 158 | + "localtoc.html", |
| 159 | + "searchbox.html" |
| 160 | + ] |
102 | 161 | } |
103 | 162 |
|
104 | 163 | # Output file base name for HTML help builder. |
|
117 | 176 | # -- Options for LaTeX output --------------------------------------- |
118 | 177 |
|
119 | 178 | latex_elements = { |
120 | | - # Paper size ("letterpaper" or "a4paper"). |
121 | | - # "papersize": "letterpaper", |
122 | | - # |
123 | | - # The font size ("10pt", "11pt" or "12pt"). |
124 | | - # "pointsize": "10pt", |
125 | | - # |
126 | | - # Additional stuff for the LaTeX preamble. |
127 | | - # "preamble": "", |
| 179 | + # Paper size ("letterpaper" or "a4paper"). |
| 180 | + # "papersize": "letterpaper", |
| 181 | + # |
| 182 | + # The font size ("10pt", "11pt" or "12pt"). |
| 183 | + # "pointsize": "10pt", |
| 184 | + # |
| 185 | + # Additional stuff for the LaTeX preamble. |
| 186 | + # "preamble": "", |
128 | 187 | } |
129 | 188 |
|
130 | 189 | # Grouping the document tree into LaTeX files. List of tuples |
131 | 190 | # (source start file, target name, title, author, |
132 | 191 | # documentclass [howto/manual]). |
133 | 192 | latex_documents = [ |
134 | | - ("index", |
135 | | - "{0}.tex".format(project), |
136 | | - "{0} Documentation".format(project), |
137 | | - author, |
138 | | - "manual") |
| 193 | + ("index", |
| 194 | + "{0}.tex".format(project), |
| 195 | + "{0} Documentation".format(project), |
| 196 | + author, |
| 197 | + "manual") |
139 | 198 | ] |
140 | 199 |
|
141 | 200 | # The name of an image file (relative to this directory) to place at |
|
163 | 222 | # One entry per manual page. List of tuples |
164 | 223 | # (source start file, name, description, authors, manual section). |
165 | 224 | man_pages = [ |
166 | | - ("index", project, |
167 | | - "{0} Documentation".format(project), |
168 | | - [author], |
169 | | - 3) |
| 225 | + ("index", project, |
| 226 | + "{0} Documentation".format(project), |
| 227 | + [author], |
| 228 | + 3) |
170 | 229 | ] |
171 | 230 |
|
172 | 231 | # If true, show URL addresses after external links. |
|
179 | 238 | # dir menu entry, description, category) |
180 | 239 |
|
181 | 240 | texinfo_documents = [ |
182 | | - ("index", |
183 | | - project, |
184 | | - "{0} Documentation".format(project), |
185 | | - author, |
186 | | - project, |
187 | | - __description__, |
188 | | - "Miscellaneous"), |
| 241 | + ("index", |
| 242 | + project, |
| 243 | + "{0} Documentation".format(project), |
| 244 | + author, |
| 245 | + project, |
| 246 | + __description__, |
| 247 | + "Miscellaneous"), |
189 | 248 | ] |
190 | 249 |
|
191 | 250 | # Documents to append as an appendix to all manuals. |
|
0 commit comments