Auto generate cli docs (#255)

* cli docs wip

* wip

* wip

* wip

* Refactoring

* wip

* Update cli docs

* Update CLI docs structure

* fixed terminal width for CLI docs

* polishing

---------

Co-authored-by: Davor Runje <[email protected]>

.pre-commit-config.yaml

@@ -5,6 +5,10 @@ repos:
     rev: v4.6.0
     hooks:
       - id: trailing-whitespace
+        exclude: |
+          (?x)^(
+              ^docs/docs/en/user-guide/cli/.*
+          )$
       - id: end-of-file-fixer
         exclude: |
           (?x)^(

docs/create_api_docs.py

@@ -2,6 +2,7 @@
 
 import itertools
 import shutil
+import textwrap
 from importlib import import_module
 from inspect import getmembers, isclass, isfunction
 from pathlib import Path
@@ -262,30 +263,44 @@ def _generate_api_docs_for_module(root_path: Path, module_name: str) -> str:
     return api_summary
 
 
+def get_navigation_template(docs_dir: Path) -> str:
+    # read summary template from file
+    navigation_template = (docs_dir / "navigation_template.txt").read_text()
+    return navigation_template
+
+
 def create_api_docs(
     root_path: Path,
     module: str,
-) -> None:
+    navigation_template: str,
+) -> str:
     """Create API documentation for a module.
 
     Args:
         root_path: The root path of the project.
         module: The name of the module.
+        navigation_template: The navigation template for the documentation.
     """
-    api = _generate_api_docs_for_module(root_path, module)
-
     docs_dir = root_path / "docs"
 
-    # read summary template from file
-    navigation_template = (docs_dir / "navigation_template.txt").read_text()
+    api = _generate_api_docs_for_module(root_path, module)
+
+    # add [API] to navigation template
+    api = textwrap.indent(api, " " * 4)
+    api = "    - API\n" + api
 
-    summary = navigation_template.format(api=api)
+    summary = navigation_template.format(api=api, cli="{cli}")
 
     summary = "\n".join(filter(bool, (x.rstrip() for x in summary.split("\n"))))
 
     (docs_dir / "SUMMARY.md").write_text(summary)
 
+    return summary
+
 
 if __name__ == "__main__":
-    root = Path(__file__).resolve().parent
-    create_api_docs(root, "fastagency")
+    root_path = Path(__file__).resolve().parent
+    docs_dir = root_path / "docs"
+
+    navigation_template = get_navigation_template(docs_dir)
+    create_api_docs(root_path, "fastagency", navigation_template)

docs/create_cli_docs.py

@@ -0,0 +1,81 @@
+import re
+import subprocess
+from pathlib import Path
+
+from create_api_docs import get_navigation_template
+
+CLI_REFERENCE_PATH = "cli"
+
+
+def _run_command_generate_docs(output_path: Path) -> str:
+    """Run the CLI command with --help and capture the output."""
+    result = subprocess.run(
+        ["typer", "fastagency.cli", "utils", "docs", "--name", "fastagency"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+
+    # replace bold tags with markdown bold
+    fix_bold = "\\[bold\\](.*?)\\[/bold\\]"
+    retval = re.sub(fix_bold, r"**\1**", result.stdout[:-1])
+
+    # replace link tags with markdown link
+    fix_link = "\\[link\\](.*?)\\[/link\\]"
+    retval = re.sub(fix_link, r"[\1](\1)", retval)
+
+    # replace color tags with markdown blue (todo: fix me)
+    for color in ["red", "green", "yellow", "blue", "magenta", "cyan", "white"]:
+        fix_color = f"\\[{color}\\](.*?)\\[/{color}\\]"
+        retval = re.sub(fix_color, r"<code>\1</code>", retval)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with output_path.open("w") as f:
+        f.write(retval)
+
+    return retval
+
+
+def _generate_cli_docs(
+    cli_name: str,
+    docs_path: Path,
+    cli_dir: str = CLI_REFERENCE_PATH,
+    cli_md_name: str = "cli.md",
+) -> str:
+    _run_command_generate_docs(docs_path / cli_dir / cli_md_name)
+    return f"    - [CLI]({cli_dir}/{cli_md_name})"
+
+
+def create_cli_docs(
+    root_path: Path,
+    module: str,
+    navigation_template: str,
+) -> str:
+    """Create CLI usage documentation for a module.
+
+    Args:
+        root_path: The root path of the project.
+        module: The name of the module.
+        navigation_template: The navigation template for the documentation.
+    """
+    docs_dir = root_path / "docs"
+
+    # Generate CLI usage documentation
+    cli = _generate_cli_docs(module, docs_dir / "en")
+
+    summary = navigation_template.format(cli=cli, api="{api}")
+
+    summary = "\n".join(filter(bool, (x.rstrip() for x in summary.split("\n"))))
+
+    (docs_dir / "SUMMARY.md").write_text(summary)
+
+    return summary
+
+
+if __name__ == "__main__":
+    root_path = Path(__file__).resolve().parent
+    docs_dir = root_path / "docs"
+
+    navigation_template = get_navigation_template(docs_dir)
+
+    create_cli_docs(root_path, "fastagency", navigation_template)

docs/docs.py

@@ -10,7 +10,8 @@
 import mkdocs.commands.build
 import mkdocs.commands.serve
 import typer
-from create_api_docs import create_api_docs
+from create_api_docs import create_api_docs, get_navigation_template
+from create_cli_docs import create_cli_docs
 from expand_markdown import expand_markdown
 from mkdocs.config import load_config
 from update_releases import _find_metablock, update_release_notes
@@ -240,14 +241,23 @@ def update_contributing():
 
 
 @app.command()
-def build_api_docs():
-    """Build api docs for fastagency."""
-    typer.echo("Updating API docs")
-    create_api_docs(root_path=BASE_DIR, module="fastagency")
+def build_api_and_cli_docs():
+    """Build api and cli docs for fastagency."""
+    typer.echo("Updating API and CLI docs")
+    docs_dir = BASE_DIR / "docs"
+
+    navigation_template = get_navigation_template(docs_dir)
+
+    navigation_template = create_api_docs(
+        root_path=BASE_DIR, module="fastagency", navigation_template=navigation_template
+    )
+    create_cli_docs(
+        root_path=BASE_DIR, module="fastagency", navigation_template=navigation_template
+    )
 
 
 def _build():
-    build_api_docs()
+    build_api_and_cli_docs()
     update_readme()
     update_contributing()