Skip to content

Commit 2816665

Browse files
Merge pull request #85 from widgetti/feat/intersphinx-objects-inv
docs: publish an intersphinx inventory
2 parents 2e9e1bc + 7e1679d commit 2816665

3 files changed

Lines changed: 55 additions & 0 deletions

File tree

‎docs/api.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -371,3 +371,29 @@ def get_widget(el: Element):
371371

372372

373373
Returns the real underlying widget, can only be used in use_effect. Note that if the same element it used twice in a component, the widget corresponding to the last element will be returned.
374+
375+
## Linking from Sphinx
376+
377+
Projects that use [Sphinx](https://www.sphinx-doc.org/) can link to this page with the
378+
[intersphinx](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) extension.
379+
Add this to your `conf.py`:
380+
381+
```py
382+
extensions = ["sphinx.ext.intersphinx"]
383+
384+
intersphinx_mapping = {
385+
"reacton": ("https://reacton.solara.dev/en/latest/", None),
386+
}
387+
```
388+
389+
Then link to a function with the `:func:` role:
390+
391+
```rst
392+
Use :func:`reacton.component` to define a component, and :func:`reacton.use_state` to keep state.
393+
```
394+
395+
To see all names in the inventory, run:
396+
397+
```bash
398+
python -m sphinx.ext.intersphinx https://reacton.solara.dev/en/latest/objects.inv
399+
```

‎hooks/objects_inv.py‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
"""Write an intersphinx inventory to the site, so Sphinx projects can link to the Reacton API docs."""
2+
3+
import re
4+
import zlib
5+
from pathlib import Path
6+
7+
HEADER = b"""# Sphinx inventory version 2
8+
# Project: Reacton
9+
# Version: latest
10+
# The remainder of this file is compressed using zlib.
11+
"""
12+
13+
14+
def inventory_body(api_markdown: str) -> bytes:
15+
# each "#### name" heading in docs/api.md documents one function
16+
names = sorted(re.findall(r"^#### (\w+)$", api_markdown, re.MULTILINE))
17+
if not names:
18+
raise ValueError("Found no API headings in docs/api.md")
19+
lines = [f"{module}.{name} py:function 1 api/#{name} -\n" for name in names for module in ["reacton", "reacton.core"]]
20+
return "".join(lines).encode("utf8")
21+
22+
23+
def on_post_build(config, **kwargs):
24+
api_markdown = (Path(config["docs_dir"]) / "api.md").read_text(encoding="utf8")
25+
output = Path(config["site_dir"]) / "objects.inv"
26+
output.write_bytes(HEADER + zlib.compress(inventory_body(api_markdown), 9))

‎mkdocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ nav:
1313
- Libraries: libraries.md
1414
- Testing: testing.md
1515

16+
hooks:
17+
- hooks/objects_inv.py
18+
1619
markdown_extensions:
1720
- pymdownx.highlight:
1821
anchor_linenums: true

0 commit comments

Comments
 (0)