diff --git a/docs/api.md b/docs/api.md index d99bec5..df030a7 100644 --- a/docs/api.md +++ b/docs/api.md @@ -371,3 +371,29 @@ def get_widget(el: Element): 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. + +## Linking from Sphinx + +Projects that use [Sphinx](https://www.sphinx-doc.org/) can link to this page with the +[intersphinx](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) extension. +Add this to your `conf.py`: + +```py +extensions = ["sphinx.ext.intersphinx"] + +intersphinx_mapping = { + "reacton": ("https://reacton.solara.dev/en/latest/", None), +} +``` + +Then link to a function with the `:func:` role: + +```rst +Use :func:`reacton.component` to define a component, and :func:`reacton.use_state` to keep state. +``` + +To see all names in the inventory, run: + +```bash +python -m sphinx.ext.intersphinx https://reacton.solara.dev/en/latest/objects.inv +``` diff --git a/hooks/objects_inv.py b/hooks/objects_inv.py new file mode 100644 index 0000000..3a22c41 --- /dev/null +++ b/hooks/objects_inv.py @@ -0,0 +1,26 @@ +"""Write an intersphinx inventory to the site, so Sphinx projects can link to the Reacton API docs.""" + +import re +import zlib +from pathlib import Path + +HEADER = b"""# Sphinx inventory version 2 +# Project: Reacton +# Version: latest +# The remainder of this file is compressed using zlib. +""" + + +def inventory_body(api_markdown: str) -> bytes: + # each "#### name" heading in docs/api.md documents one function + names = sorted(re.findall(r"^#### (\w+)$", api_markdown, re.MULTILINE)) + if not names: + raise ValueError("Found no API headings in docs/api.md") + lines = [f"{module}.{name} py:function 1 api/#{name} -\n" for name in names for module in ["reacton", "reacton.core"]] + return "".join(lines).encode("utf8") + + +def on_post_build(config, **kwargs): + api_markdown = (Path(config["docs_dir"]) / "api.md").read_text(encoding="utf8") + output = Path(config["site_dir"]) / "objects.inv" + output.write_bytes(HEADER + zlib.compress(inventory_body(api_markdown), 9)) diff --git a/mkdocs.yml b/mkdocs.yml index c11a6ab..87fdb19 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,9 @@ nav: - Libraries: libraries.md - Testing: testing.md +hooks: + - hooks/objects_inv.py + markdown_extensions: - pymdownx.highlight: anchor_linenums: true