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) |
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
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. :)
All reactions