Restructuring the docs #1531
Unanswered
florimondmanca
asked this question in
Ideas
Restructuring the docs
#1531
Replies: 1 comment
-
|
I've got a local branch with a possible restructuration, and I wrote a small script to generate the resulting file and headers structure, here it is… Each 1st-level bullet point is a tab (if contains children), or a link in the home page sidebar. 2nd-level bullet points are pages in the sidebar of the corresponding tab, and 3rd-level or more are links in the right-hand sidebar. I'm not sure about the "API Reference section inside usage guide page" style is exactly preferable to "one page with all API Reference you'll ever need", At first I thought the main pro was in terms of effectively putting cross-references. But that's also possible as eg Preview
Docs structure listing
Generation script: from typing import Iterator, List
import yaml
from pathlib import Path
import re
HEADER_RE = re.compile(r"^(?P<level>#+) (?P<text>.*)")
LINK_RE = re.compile(r"^\[(?P<text>.+)\]\(.+\)")
INDENT = 2 * " "
def _generate_file_structure(path: Path) -> Iterator[str]:
md = path.read_text()
in_code_block = False
for line in md.splitlines():
line = line.strip()
if not line:
continue
if line.startswith("```"):
in_code_block = not in_code_block
continue
if in_code_block:
continue
m = HEADER_RE.match(line)
if m is None:
continue
level = len(m.group("level")) # 1, 2, ...
text = m.group("text")
m = LINK_RE.match(text)
if m is not None:
text = m.group("text")
yield f"{level * INDENT}* {text}"
def generate_markdown_tree() -> Iterator[str]:
with open("mkdocs.yml") as f:
mkdocs_yml: dict = yaml.safe_load(f)
nav: List[dict] = mkdocs_yml["nav"]
for entry in nav:
name, value = entry.popitem()
assert not entry
yield f"* {name}"
if isinstance(value, str):
# Top-level page
continue
# Section with children
assert isinstance(value, list)
for filename in value:
path = Path("docs", filename)
for line in _generate_file_structure(path):
yield 2 * " " + line
if __name__ == "__main__":
output = "\n".join(generate_markdown_tree())
print(output) |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
I think this got quickly mentioned by @tomchristie somewhere around here some time ago, and I pretty much agree, so here's an issue to track it.
Right now the structure of our docs is okay, but there's a lot of room for improvement.
For example:
I'll be posting a proposed docs structure, just shifting things around so they're nicely grouped into "topic guides" which I think can go a long way in making the docs more helpful as a whole. :)
Beta Was this translation helpful? Give feedback.
All reactions