Skip to content

Commit 9f74b5f

Browse files
rmorshearmorshea
committed
improve auto gen api docs
1 parent 24aed28 commit 9f74b5f

File tree

8 files changed

+79
-67
lines changed

8 files changed

+79
-67
lines changed

‎docs/main.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import os
22
import sys
3+
from functools import partial
34
from pathlib import Path
45

56
from sanic import Sanic, response
@@ -43,7 +44,7 @@ async def forward_to_index(request):
4344

4445
# Modify the run function so when we exec the file
4546
# instead of running a server we mount the view.
46-
idom.run = mount[file.stem]
47+
idom.run = partial(mount.add, file.stem)
4748

4849
with file.open() as f:
4950
try:

‎docs/source/_exts/autogen_api_docs.py

+50-23
Original file line numberDiff line numberDiff line change
@@ -5,43 +5,70 @@
55

66
HERE = Path(__file__).parent
77
PACKAGE_SRC = HERE.parent.parent.parent / "src"
8-
PUBLIC_API_REFERENCE_FILE = HERE.parent / "api-reference.rst"
9-
PRIVATE_API_REFERENCE_FILE = HERE.parent / "developer-apis.rst"
108

9+
AUTO_DIR = HERE.parent / "auto"
10+
AUTO_DIR.mkdir(exist_ok=True)
1111

12-
PUBLIC_TITLE = """API Reference
13-
=============
14-
"""
12+
PUBLIC_API_REFERENCE_FILE = AUTO_DIR / "api-reference.rst"
13+
PRIVATE_API_REFERENCE_FILE = AUTO_DIR / "developer-apis.rst"
1514

16-
PRIVATE_TITLE = """Developer APIs
17-
==============
18-
"""
1915

20-
AUTODOC_TEMPLATE = """
21-
.. automodule:: {module}
22-
:members:
23-
"""
16+
PUBLIC_TITLE = "API Reference\n=============\n"
17+
PUBLIC_MISC_TITLE = "Misc Modules\n------------\n"
18+
PRIVATE_TITLE = "Developer APIs\n==============\n"
19+
PRIVATE_MISC_TITLE = "Misc Dev Modules\n----------------\n"
2420

25-
26-
def make_autodoc_section(module_name: str) -> str:
27-
return AUTODOC_TEMPLATE.format(module=module_name, underline="-" * len(module_name))
21+
AUTODOC_TEMPLATE = ".. automodule:: {module}\n :members:\n"
2822

2923

3024
def generate_api_docs():
31-
public_docs = [PUBLIC_TITLE]
32-
private_docs = [PRIVATE_TITLE]
25+
docs = {
26+
"public.main": [PUBLIC_TITLE],
27+
"public.misc": [PUBLIC_MISC_TITLE],
28+
"private.main": [PRIVATE_TITLE],
29+
"private.misc": [PRIVATE_MISC_TITLE],
30+
}
3331

3432
for file in sorted(PACKAGE_SRC.glob("**/*.py")):
3533
if file.stem.startswith("__"):
3634
# skip __init__ and __main__
3735
continue
38-
rel_path = file.relative_to(PACKAGE_SRC)
39-
module_name = ".".join(rel_path.with_suffix("").parts)
40-
api_docs = make_autodoc_section(module_name)
41-
(private_docs if "._" in module_name else public_docs).append(api_docs)
36+
public_vs_private = "private" if is_private_module(file) else "public"
37+
main_vs_misc = "main" if file_starts_with_docstring(file) else "misc"
38+
key = f"{public_vs_private}.{main_vs_misc}"
39+
docs[key].append(make_autodoc_section(file, public_vs_private == "private"))
40+
41+
public_content = docs["public.main"]
42+
if len(docs["public.misc"]) > 1:
43+
public_content += docs["public.misc"]
44+
45+
private_content = docs["private.main"]
46+
if len(docs["private.misc"]) > 1:
47+
private_content += docs["private.misc"]
48+
49+
PUBLIC_API_REFERENCE_FILE.write_text("\n".join(public_content))
50+
PRIVATE_API_REFERENCE_FILE.write_text("\n".join(private_content))
51+
4252

43-
PUBLIC_API_REFERENCE_FILE.write_text("\n".join(public_docs))
44-
PRIVATE_API_REFERENCE_FILE.write_text("\n".join(private_docs))
53+
def is_private_module(path: Path) -> bool:
54+
return any(p.startswith("_") for p in path.parts)
55+
56+
57+
def make_autodoc_section(path: Path, is_public) -> str:
58+
rel_path = path.relative_to(PACKAGE_SRC)
59+
module_name = ".".join(rel_path.with_suffix("").parts)
60+
return AUTODOC_TEMPLATE.format(module=module_name, underline="-" * len(module_name))
61+
62+
63+
def file_starts_with_docstring(path: Path) -> bool:
64+
for line in path.read_text().split("\n"):
65+
if line.startswith("#"):
66+
continue
67+
if line.startswith('"""') or line.startswith("'''"):
68+
return True
69+
else:
70+
break
71+
return False
4572

4673

4774
def setup(app: Sphinx) -> None:

‎docs/source/api-reference.rst renamed to ‎docs/source/auto/api-reference.rst

+13-34
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,77 @@
11
API Reference
22
=============
33

4-
5-
.. automodule:: idom.cli
6-
:members:
7-
8-
94
.. automodule:: idom.client.manage
105
:members:
116

12-
137
.. automodule:: idom.client.module
148
:members:
159

16-
1710
.. automodule:: idom.config
1811
:members:
1912

20-
2113
.. automodule:: idom.core.component
2214
:members:
2315

24-
2516
.. automodule:: idom.core.dispatcher
2617
:members:
2718

28-
2919
.. automodule:: idom.core.events
3020
:members:
3121

32-
3322
.. automodule:: idom.core.hooks
3423
:members:
3524

36-
3725
.. automodule:: idom.core.layout
3826
:members:
3927

40-
41-
.. automodule:: idom.core.utils
42-
:members:
43-
44-
4528
.. automodule:: idom.core.vdom
4629
:members:
4730

48-
4931
.. automodule:: idom.dialect
5032
:members:
5133

52-
5334
.. automodule:: idom.log
5435
:members:
5536

56-
57-
.. automodule:: idom.server.base
58-
:members:
59-
60-
6137
.. automodule:: idom.server.fastapi
6238
:members:
6339

64-
6540
.. automodule:: idom.server.flask
6641
:members:
6742

68-
6943
.. automodule:: idom.server.prefab
7044
:members:
7145

72-
7346
.. automodule:: idom.server.sanic
7447
:members:
7548

76-
7749
.. automodule:: idom.server.tornado
7850
:members:
7951

52+
.. automodule:: idom.testing
53+
:members:
8054

81-
.. automodule:: idom.server.utils
55+
.. automodule:: idom.utils
8256
:members:
8357

58+
.. automodule:: idom.widgets.html
59+
:members:
8460

85-
.. automodule:: idom.testing
61+
.. automodule:: idom.widgets.utils
8662
:members:
8763

64+
Misc Modules
65+
------------
8866

89-
.. automodule:: idom.utils
67+
.. automodule:: idom.cli
9068
:members:
9169

92-
93-
.. automodule:: idom.widgets.html
70+
.. automodule:: idom.core.utils
9471
:members:
9572

73+
.. automodule:: idom.server.base
74+
:members:
9675

97-
.. automodule:: idom.widgets.utils
76+
.. automodule:: idom.server.utils
9877
:members:

‎docs/source/developer-apis.rst renamed to ‎docs/source/auto/developer-apis.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
Developer APIs
22
==============
33

4-
54
.. automodule:: idom._option
65
:members:
76

7+
Misc Dev Modules
8+
----------------
89

910
.. automodule:: idom.client._private
1011
:members:

‎docs/source/conf.py

+5-4
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,6 @@
5454
"sphinx.ext.extlinks",
5555
"sphinx.ext.autosectionlabel",
5656
# third party extensions
57-
"sphinx_autodoc_typehints",
5857
"sphinx_panels",
5958
"sphinx_copybutton",
6059
"sphinx_reredirects",
@@ -97,6 +96,9 @@
9796
# The default language to highlight source code in.
9897
highlight_language = "python3"
9998

99+
# Controls how sphinx.ext.autodoc represents typehints in the function signature
100+
autodoc_typehints = "description"
101+
100102
# -- Extension Configuration ------------------------------------------------------
101103

102104
# -- sphinx_panel --
@@ -110,7 +112,6 @@
110112
# show base classes for autodoc
111113
autodoc_default_options = {
112114
"show-inheritance": True,
113-
"inherited-members": True,
114115
"member-order": "bysource",
115116
}
116117
# order autodoc members by their order in the source
@@ -119,8 +120,8 @@
119120
# -- sphinx_reredirects --
120121

121122
redirects = {
122-
"package-api": "api-reference.html",
123-
"configuration-options": "api-reference.html#configuration-options",
123+
"package-api": "auto/api-reference.html",
124+
"configuration-options": "auto/api-reference.html#configuration-options",
124125
}
125126

126127
# -- Options for HTML output -------------------------------------------------

‎docs/source/index.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Libraries for defining and controlling interactive webpages with Python
1010
installation
1111
getting-started
1212
life-cycle-hooks
13-
api-reference
13+
auto/api-reference
1414
examples
1515

1616
.. toctree::
@@ -28,7 +28,7 @@ Libraries for defining and controlling interactive webpages with Python
2828

2929
contributing
3030
developer-guide
31-
developer-apis
31+
auto/developer-apis
3232
changelog
3333
roadmap
3434

‎noxfile.py

+4-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,8 @@ def docs(session: Session) -> None:
4444
"python",
4545
"scripts/live_docs.py",
4646
"--open-browser",
47-
"--ignore=build/**/*",
47+
# for some reason this matches absolute paths
48+
"--ignore=**/docs/source/auto/*",
4849
"-a",
4950
"-E",
5051
"-b",
@@ -198,3 +199,5 @@ def install_idom_dev(session: Session, extras: str = "stable") -> None:
198199
session.install("-e", f".[{extras}]")
199200
if "--no-restore" not in session.posargs:
200201
session.run("idom", "restore")
202+
else:
203+
session.posargs.remove("--no-restore")

‎requirements/build-docs.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
sphinx ==3.2.1
1+
sphinx ==3.5.4
22
sphinx-autodoc-typehints ==1.7.0
33
furo ==2020.10.13b12
44
sphinx-panels ==0.5.0

0 commit comments

Comments
 (0)