Auto-generate CLI doc pages (#1325)

microsoft · Oct 25, 2024 · 083de12 · 083de12
1 parent d6e6f5c
commit 083de12
Show file tree

Hide file tree

Showing 10 changed files with 36 additions and 75 deletions.
diff --git a/.semversioner/next-release/patch-20241025215416188681.json b/.semversioner/next-release/patch-20241025215416188681.json
@@ -0,0 +1,4 @@
+{
+  "type": "patch",
+  "description": "add-autogenerated-cli-docs"
+}
diff --git a/dictionary.txt b/dictionary.txt
@@ -67,6 +67,7 @@ pypi
 nbformat
 semversioner
 mkdocs
+typer
 
 # Library Methods
 iterrows

diff --git a/docs/cli.md b/docs/cli.md
@@ -0,0 +1,9 @@
+# CLI Reference
+
+This page documents the command-line interface of the graphrag library.
+
+::: mkdocs-typer
+    :module: graphrag.cli.main
+    :prog_name: graphrag
+    :command: app
+    :depth: 0
diff --git a/docs/get_started.md b/docs/get_started.md
@@ -30,6 +30,8 @@ It shows how to use the system to index some text, and then use the indexed data
 pip install graphrag
 ```
 
+The graphrag library includes a CLI for a no-code approach to getting started. Please review the full [CLI documentation](cli.md) for further detail.
+
 # Running the Indexer
 
 Now we need to set up a data project and some initial configuration. Let's set that up. We're using the [default configuration mode](config/overview.md), which you can customize as needed using a [config file](config/json_yaml.md), which we recommend, or [environment variables](config/env_vars.md).

diff --git a/docs/index/cli.md b/docs/index/cli.md
diff --git a/docs/query/cli.md b/docs/query/cli.md
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -29,7 +29,6 @@ nav:
       - Overview: "index/overview.md"
       - Architecture: "index/architecture.md"
       - Dataflow: "index/default_dataflow.md"
-      - CLI: "index/cli.md"
       - Configuration:
           - Overview: "config/overview.md"
           - Init Command: "config/init.md"
@@ -46,13 +45,13 @@ nav:
       - Local Search: "query/local_search.md"
       - Question Generation: "query/question_generation.md"
       - Global Search: "query/global_search.md"
-      - CLI: "query/cli.md"
       - Notebooks:
           - Overview: "query/notebooks/overview.md"
           - Global Search: "examples_notebooks/global_search.ipynb"
           - Local Search: "examples_notebooks/local_search.ipynb"
   - Microsoft Research Blog: "blog_posts.md"
   - Extras:
+      - CLI: "cli.md"
       - Operation Dulce:
           - About: "data/operation_dulce/ABOUT.md"
           - Document: "data/operation_dulce/Operation Dulce v2 1 1.md"
@@ -104,3 +103,4 @@ markdown_extensions:
       slugify: !!python/object/apply:pymdownx.slugs.slugify
         kwds:
           case: lower
+  - mkdocs-typer
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -92,6 +92,7 @@ json-repair = "^0.30.0"
 future = "^1.0.0" # Needed until graspologic fixes their dependency
 typer = "^0.12.5"
 
+mkdocs-typer = "^0.0.3"
 [tool.poetry.group.dev.dependencies]
 coverage = "^7.6.0"
 ipykernel = "^6.29.4"

diff --git a/tests/unit/config/test_default_config.py b/tests/unit/config/test_default_config.py
@@ -482,20 +482,16 @@ def test_can_set_no_chunk_by_columns(self):
 
     def test_all_env_vars_is_accurate(self):
         env_var_docs_path = Path("docs/config/env_vars.md")
-        query_docs_path = Path("docs/query/cli.md")
 
         env_var_docs = env_var_docs_path.read_text(encoding="utf-8")
-        query_docs = query_docs_path.read_text(encoding="utf-8")
 
         def find_envvar_names(text) -> set[str]:
             pattern = r"`(GRAPHRAG_[^`]+)`"
             found = re.findall(pattern, text)
             found = {f for f in found if not f.endswith("_")}
             return {*found}
 
-        graphrag_strings = find_envvar_names(env_var_docs) | find_envvar_names(
-            query_docs
-        )
+        graphrag_strings = find_envvar_names(env_var_docs)
 
         missing = {s for s in graphrag_strings if s not in ALL_ENV_VARS} - {
             # Remove configs covered by the base LLM connection configs