|
17 | 17 | # |
18 | 18 | # SPDX-License-Identifier: MIT |
19 | 19 |
|
20 | | -import json |
21 | 20 | import logging |
22 | 21 | import os |
| 22 | +import re |
23 | 23 | import subprocess |
24 | 24 | import sys |
25 | 25 | import urllib.parse |
26 | 26 |
|
27 | 27 | import recommonmark |
| 28 | +from sphinx.transforms import SphinxTransform |
| 29 | +from docutils import nodes |
| 30 | +from sphinx import addnodes |
28 | 31 |
|
29 | 32 | # If extensions (or modules to document with autodoc) are in another directory, |
30 | 33 | # add these directories to sys.path here. If the directory is relative to the |
|
39 | 42 | # Grab the JSON values to use while building the module support matrix |
40 | 43 | # in 'shared-bindings/index.rst' |
41 | 44 |
|
| 45 | +# The stubs must be built before we calculate the shared bindings matrix |
| 46 | +subprocess.check_output(["make", "stubs"]) |
| 47 | + |
42 | 48 | #modules_support_matrix = shared_bindings_matrix.support_matrix_excluded_boards() |
43 | 49 | modules_support_matrix = shared_bindings_matrix.support_matrix_by_board() |
44 | 50 |
|
|
74 | 80 | '.md': 'markdown', |
75 | 81 | } |
76 | 82 |
|
77 | | -subprocess.check_output(["make", "stubs"]) |
78 | 83 | extensions.append('autoapi.extension') |
79 | 84 |
|
80 | 85 | autoapi_type = 'python' |
|
84 | 89 | autoapi_add_toctree_entry = False |
85 | 90 | autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary'] |
86 | 91 | autoapi_template_dir = 'docs/autoapi/templates' |
| 92 | +autoapi_python_class_content = "both" |
87 | 93 | autoapi_python_use_implicit_namespaces = True |
88 | 94 | autoapi_root = "shared-bindings" |
89 | 95 |
|
|
106 | 112 | # |
107 | 113 | # We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags" |
108 | 114 | # breakdown, so use the same version identifier for both to avoid confusion. |
109 | | -version = release = '0.0.0' |
| 115 | + |
| 116 | +final_version = "" |
| 117 | +git_describe = subprocess.run( |
| 118 | + ["git", "describe", "--dirty", "--tags"], |
| 119 | + stdout=subprocess.PIPE, |
| 120 | + stderr=subprocess.STDOUT, |
| 121 | + encoding="utf-8" |
| 122 | +) |
| 123 | +if git_describe.returncode == 0: |
| 124 | + git_version = re.search( |
| 125 | + r"^\d(?:\.\d){0,2}(?:\-(?:alpha|beta|rc)\.\d+){0,1}", |
| 126 | + str(git_describe.stdout) |
| 127 | + ) |
| 128 | + if git_version: |
| 129 | + final_version = git_version[0] |
| 130 | +else: |
| 131 | + print("Failed to retrieve git version:", git_describe.stdout) |
| 132 | + |
| 133 | +version = release = final_version |
110 | 134 |
|
111 | 135 | # The language for content autogenerated by Sphinx. Refer to documentation |
112 | 136 | # for a list of supported languages. |
|
122 | 146 | # directories to ignore when looking for source files. |
123 | 147 | exclude_patterns = ["**/build*", |
124 | 148 | ".git", |
| 149 | + ".env", |
125 | 150 | ".venv", |
126 | 151 | ".direnv", |
127 | 152 | "docs/autoapi", |
@@ -423,7 +448,38 @@ def generate_redirects(app): |
423 | 448 | with open(redirected_filename, 'w') as f: |
424 | 449 | f.write(TEMPLATE % urllib.parse.quote(to_path, '#/')) |
425 | 450 |
|
| 451 | + |
| 452 | +class CoreModuleTransform(SphinxTransform): |
| 453 | + default_priority = 870 |
| 454 | + |
| 455 | + def _convert_first_paragraph_into_title(self): |
| 456 | + title = self.document.next_node(nodes.title) |
| 457 | + paragraph = self.document.next_node(nodes.paragraph) |
| 458 | + if not title or not paragraph: |
| 459 | + return |
| 460 | + if isinstance(paragraph[0], nodes.paragraph): |
| 461 | + paragraph = paragraph[0] |
| 462 | + if all(isinstance(child, nodes.Text) for child in paragraph.children): |
| 463 | + for child in paragraph.children: |
| 464 | + title.append(nodes.Text(" \u2013 ")) |
| 465 | + title.append(child) |
| 466 | + paragraph.parent.remove(paragraph) |
| 467 | + |
| 468 | + def _enable_linking_to_nonclass_targets(self): |
| 469 | + for desc in self.document.traverse(addnodes.desc): |
| 470 | + for xref in desc.traverse(addnodes.pending_xref): |
| 471 | + if xref.attributes.get("reftype") == "class": |
| 472 | + xref.attributes.pop("refspecific", None) |
| 473 | + |
| 474 | + def apply(self, **kwargs): |
| 475 | + docname = self.env.docname |
| 476 | + if docname.startswith(autoapi_root) and docname.endswith("/index"): |
| 477 | + self._convert_first_paragraph_into_title() |
| 478 | + self._enable_linking_to_nonclass_targets() |
| 479 | + |
| 480 | + |
426 | 481 | def setup(app): |
427 | 482 | app.add_css_file("customstyle.css") |
428 | 483 | app.add_config_value('redirects_file', 'redirects', 'env') |
429 | 484 | app.connect('builder-inited', generate_redirects) |
| 485 | + app.add_transform(CoreModuleTransform) |
0 commit comments