Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 842ad01

Browse files
committed
feat: filter content for mkdocstrings
- Filter out `_something` files in `plotly/graph_objects`. - Move their content to `something`. - General refactoring of `bin/generate_references_pages.py` to be more readable. TODO: get the class name like `Bar` into the ToC rather than `plotly.graph_objects.bar`.
1 parent 0fa35da commit 842ad01

File tree

2 files changed

+105
-49
lines changed

2 files changed

+105
-49
lines changed

‎Makefile‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ PACKAGE_DIRS = _plotly_utils plotly
55
CODE_DIRS = ${PACKAGE_DIRS} scripts
66
EXAMPLE_SRC = $(wildcard doc/python/*.md)
77
EXAMPLE_DST = $(patsubst doc/python/%.md,pages/examples/%.md,${EXAMPLE_SRC})
8+
MKDOCS_TEMP_DIR = ./docs_tmp
89

910
## commands: show available commands
1011
commands:
@@ -21,7 +22,8 @@ docs-lint:
2122

2223
## docs-tmp: rebuild documentation saving Markdown in ./tmp
2324
docs-tmp:
24-
MKDOCS_TEMP_DIR=./docs_tmp ${RUN} mkdocs build
25+
@rm -rf ${MKDOCS_TEMP_DIR}
26+
MKDOCS_TEMP_DIR=${MKDOCS_TEMP_DIR} ${RUN} mkdocs build
2527

2628
## examples: generate Markdown for individual doc/python
2729
examples: ${EXAMPLE_DST}

‎bin/generate_reference_pages.py‎

Lines changed: 102 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -5,54 +5,108 @@
55

66
import mkdocs_gen_files
77

8+
OUTPUT_ROOT = Path("reference")
9+
SUMMARY_FILE = Path("SUMMARY.md")
10+
INDEX_FILE = "index.md"
11+
12+
SKIP_DIR = "graph_objects"
13+
14+
CONTENT = """
15+
# {title}
16+
17+
::: {ident}
18+
"""
19+
20+
21+
def main():
22+
"""Main driver."""
23+
24+
# Setup.
25+
temp_dir = _get_temp_dir()
26+
nav = mkdocs_gen_files.Nav()
27+
28+
# Process each Python file.
29+
for path in sorted(Path("plotly").rglob("*.py")):
30+
if _skip_file(path):
31+
continue
32+
33+
# Paths.
34+
module_path = path.relative_to(".").with_suffix("")
35+
doc_path = path.relative_to(".").with_suffix(".md")
36+
full_doc_path = OUTPUT_ROOT / doc_path
37+
38+
# Dunder special cases.
39+
parts = tuple(module_path.parts)
40+
if parts[-1] == "__main__":
41+
continue
42+
if parts[-1] == "__init__":
43+
parts = parts[:-1]
44+
doc_path = doc_path.with_name(INDEX_FILE)
45+
full_doc_path = full_doc_path.with_name(INDEX_FILE)
46+
47+
# Save constructed data.
48+
nav[parts] = doc_path.as_posix()
49+
mkdocs_gen_files.set_edit_path(full_doc_path, path)
50+
content = _make_content(parts)
51+
_save_in_memory(full_doc_path, content)
52+
_save_in_temp_dir(temp_dir, doc_path, content)
53+
54+
# Generate navigation summary.
55+
_generate_nav_summary(temp_dir, nav)
56+
57+
58+
def _generate_nav_summary(temp_dir, nav):
59+
"""Create navigation summary (saving if requested)."""
60+
lines = nav.build_literate_nav()
61+
62+
with mkdocs_gen_files.open(OUTPUT_ROOT / SUMMARY_FILE, "w") as writer:
63+
writer.writelines(lines)
864

9-
# Saving Markdown files?
10-
temp_dir = os.getenv("MKDOCS_TEMP_DIR", None)
11-
if temp_dir is not None:
12-
temp_dir = Path(temp_dir)
13-
14-
# Set up the generation engine.
15-
nav = mkdocs_gen_files.Nav()
16-
17-
# Match each Python file.
18-
for path in sorted(Path("plotly").rglob("*.py")):
19-
# Documentation path.
20-
module_path = path.relative_to(".").with_suffix("")
21-
doc_path = path.relative_to(".").with_suffix(".md")
22-
full_doc_path = Path("reference", doc_path)
23-
24-
# Handle dunder special cases.
25-
parts = tuple(module_path.parts)
26-
if parts[-1] == "__init__":
27-
parts = parts[:-1]
28-
doc_path = doc_path.with_name("index.md")
29-
full_doc_path = full_doc_path.with_name("index.md")
30-
elif parts[-1] == "__main__":
31-
continue
32-
33-
# Save constructed data.
34-
nav[parts] = doc_path.as_posix()
35-
mkdocs_gen_files.set_edit_path(full_doc_path, path)
36-
37-
# Save in-memory file.
38-
with mkdocs_gen_files.open(full_doc_path, "w") as writer:
39-
ident = ".".join(parts)
40-
writer.write(f"# {ident}\n\n")
41-
writer.write(f"::: {ident}")
42-
43-
# Save to disk if requested.
4465
if temp_dir is not None:
45-
temp_path = temp_dir / doc_path
46-
temp_path.parent.mkdir(exist_ok=True, parents=True)
47-
with open(temp_path, "w") as writer:
48-
ident = ".".join(parts)
49-
writer.write(f"# {ident}\n\n")
50-
writer.write(f"::: {ident}")
51-
52-
# Generate navigation summary.
53-
with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as writer:
54-
writer.writelines(nav.build_literate_nav())
55-
if temp_dir is not None:
56-
temp_path = temp_dir / "SUMMARY.md"
66+
with open(temp_dir / SUMMARY_FILE, "w") as writer:
67+
writer.writelines(lines)
68+
69+
70+
def _get_temp_dir():
71+
"""Get temporary directory for on-disk files if requested."""
72+
temp_dir = os.getenv("MKDOCS_TEMP_DIR", None)
73+
if temp_dir is not None:
74+
temp_dir = Path(temp_dir)
75+
return temp_dir
76+
77+
78+
def _make_content(parts):
79+
"""Generate text to put in files."""
80+
ident = parts
81+
if (len(parts) == 3) and (parts[1] == SKIP_DIR) and (parts[2] != SKIP_DIR):
82+
ident = [*parts[:-1], f"_{parts[2]}"]
83+
return CONTENT.format(title=".".join(parts), ident=".".join(ident))
84+
85+
86+
def _save_in_memory(output_path, content):
87+
"""Save in-memory file."""
88+
with mkdocs_gen_files.open(output_path, "w") as writer:
89+
writer.write(content)
90+
91+
92+
def _save_in_temp_dir(temp_dir, doc_path, content):
93+
"""Save on-disk file."""
94+
if temp_dir is None:
95+
return
96+
97+
temp_path = temp_dir / doc_path
98+
temp_path.parent.mkdir(exist_ok=True, parents=True)
5799
with open(temp_path, "w") as writer:
58-
writer.writelines(nav.build_literate_nav())
100+
writer.write(content)
101+
102+
103+
def _skip_file(path):
104+
"""Don't include files like 'graph_objects/_bar.py'."""
105+
return (
106+
path.is_file() and (path.parent.name == SKIP_DIR) and str(path.name).startswith("_")
107+
)
108+
109+
110+
# Do NOT protect this with `if __name__ == "__main__"` because this is
111+
# run as a plugin by MkDocs rather than as a top-level script.
112+
main()

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /