diff options
author | 2021-12-09 20:52:54 +0400 | |
---|---|---|
committer | 2021-12-13 18:49:38 +0400 | |
commit | 1b098fc6dc0bbd6b5715f63b6f68e876cf1b45ed (patch) | |
tree | 878c7557d7cfcb78d9ae0754a07f82ea45f4f449 | |
parent | Add InterSphinx Extension (diff) |
Modify Autodoc Formatting
Changes the style of the reformatted autodoc files to look nicer with
submodules.
-rw-r--r-- | docs/conf.py | 34 | ||||
-rw-r--r-- | pyproject.toml | 2 |
2 files changed, 17 insertions, 19 deletions
diff --git a/docs/conf.py b/docs/conf.py index 864168f6..142ceb41 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -99,31 +99,29 @@ def __cleanup() -> None: # We only have one module, so this is redundant # Remove it and flatten out the tree file.unlink() + continue - elif file.name == "botcore.rst": - # We want to bring the submodule name to the top, and remove anything that's not a submodule - result = "" - for line in file.read_text(encoding="utf-8").splitlines(keepends=True): - if ".." not in line and result == "": - # We have not reached the first submodule, this is all filler - continue - elif "Module contents" in line: - # We have parsed all the submodules, so let's skip the redudant module name - break - result += line + elif file.name in ("botcore.rst", "botcore.exts.rst"): + content = file.read_text(encoding="utf-8").splitlines(keepends=True) + + # Rename the extension to be less wordy + # Example: botcore.exts -> Botcore Exts + title = content[0].split()[0].strip().replace("botcore.", "").replace(".", " ").title() + title = f"{title}\n{'=' * len(title)}\n\n" + content[0:2] = title - result = "Botcore\n=======\n\n" + result - file.write_text(result, encoding="utf-8") + file.write_text("".join(content), encoding="utf-8") else: # Clean up the submodule name so it's just the name without the top level module name # example: `botcore.regex module` -> `regex` - lines = file.read_text(encoding="utf-8").splitlines() - lines[0] = lines[0].replace("botcore.", "").replace("module", "").strip() + lines = file.read_text(encoding="utf-8").splitlines(keepends=True) + lines[0] = lines[0].replace("module", "").strip().split(".")[-1] + "\n" + file.write_text("".join(lines)) - # Take the opportunity to configure autodoc - lines = "\n".join(lines).replace("undoc-members", "special-members") - file.write_text(lines, encoding="utf-8") + # Take the opportunity to configure autodoc + content = file.read_text(encoding="utf-8").replace("undoc-members", "special-members") + file.write_text(content, encoding="utf-8") __cleanup() diff --git a/pyproject.toml b/pyproject.toml index c0a57862..59ce321b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,7 +45,7 @@ furo = "^2021.11.23" [tool.taskipy.tasks] lint = "pre-commit run --all-files" precommit = "pre-commit install" -apidoc = "sphinx-apidoc -o docs/output botcore -fe" +apidoc = "sphinx-apidoc -o docs/output botcore -feM" builddoc = "sphinx-build -nW -j auto -b html docs docs/build" docs = "task apidoc && task builddoc" |