docs: add automatic generation of CLI reference (#325)

* docs: add automatic generation of CLI reference Signed-off-by: Michele Dolfi <[email protected]> * install deps for building CLI ref Signed-off-by: Michele Dolfi <[email protected]> --------- Signed-off-by: Michele Dolfi <[email protected]>
DS4SD · Nov 15, 2024 · ca8524e · ca8524e
1 parent 25fd149
commit ca8524e
Show file tree

Hide file tree

Showing 7 changed files with 48 additions and 68 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -11,15 +11,7 @@ jobs:
         runs-on: ubuntu-latest
         steps:
         - uses: actions/checkout@v4
-        - name: Install poetry
-          run: pipx install poetry==1.8.3
-          shell: bash
-        - uses: actions/setup-python@v5
-          with:
-              cache: 'poetry'
-        - name: Install dependencies
-          run: poetry install --only docs
-          shell: bash
+        - uses: ./.github/actions/setup-poetry
         - name: Build docs
           run: poetry run mkdocs build --verbose --clean
         - name: Build and push docs

diff --git a/docling/cli/main.py b/docling/cli/main.py
@@ -301,5 +301,7 @@ def convert(
     _log.info(f"All documents were converted in {end_time:.2f} seconds.")
 
 
+click_app = typer.main.get_command(app)
+
 if __name__ == "__main__":
     app()
diff --git a/docs/cli.md b/docs/cli.md
@@ -0,0 +1,9 @@
+# CLI Reference
+
+This page provides documentation for our command line tools.
+
+::: mkdocs-click
+    :module: docling.cli.main
+    :command: click_app
+    :prog_name: docling
+    :style: table
diff --git a/docs/usage.md b/docs/usage.md
@@ -22,54 +22,7 @@ A simple example would look like this:
 docling https://arxiv.org/pdf/2206.01062
 ```
 
-To see all available options (export formats etc.) run `docling --help`.
-
-<details>
-  <summary><b>CLI reference</b></summary>
-
-Here are the available options as of this writing (for an up-to-date listing, run `docling --help`):
-
-```console
-$ docling --help
-
- Usage: docling [OPTIONS] source                                                                                             
-                                                                                                                             
-╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
-│ *    input_sources      source  PDF files to convert. Can be local file / directory paths or URL. [default: None]         │
-│                                 [required]                                                                                │
-╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
-╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
-│ --from                                     [docx|pptx|html|image|pdf|asciidoc|md]  Specify input formats to convert from. │
-│                                                                                    Defaults to all formats.               │
-│                                                                                    [default: None]                        │
-│ --to                                       [md|json|text|doctags]                  Specify output formats. Defaults to    │
-│                                                                                    Markdown.                              │
-│                                                                                    [default: None]                        │
-│ --ocr               --no-ocr                                                       If enabled, the bitmap content will be │
-│                                                                                    processed using OCR.                   │
-│                                                                                    [default: ocr]                         │
-│ --ocr-engine                               [easyocr|tesseract_cli|tesseract]       The OCR engine to use.                 │
-│                                                                                    [default: easyocr]                     │
-│ --pdf-backend                              [pypdfium2|dlparse_v1|dlparse_v2]       The PDF backend to use.                │
-│                                                                                    [default: dlparse_v1]                  │
-│ --table-mode                               [fast|accurate]                         The mode to use in the table structure │
-│                                                                                    model.                                 │
-│                                                                                    [default: fast]                        │
-│ --artifacts-path                           PATH                                    If provided, the location of the model │
-│                                                                                    artifacts.                             │
-│                                                                                    [default: None]                        │
-│ --abort-on-error    --no-abort-on-error                                            If enabled, the bitmap content will be │
-│                                                                                    processed using OCR.                   │
-│                                                                                    [default: no-abort-on-error]           │
-│ --output                                   PATH                                    Output directory where results are     │
-│                                                                                    saved.                                 │
-│                                                                                    [default: .]                           │
-│ --version                                                                          Show version information.              │
-│ --help                                                                             Show this message and exit.            │
-╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
-
-```
-</details>
+To see all available options (export formats etc.) run `docling --help`. More details in the [CLI reference page](./cli.md).
 
 
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -55,6 +55,7 @@ nav:
     - Home: index.md
     - Installation: installation.md
     - Usage: usage.md
+    - CLI: cli.md
     - Docling v2: v2.md
   - Concepts:
     - Concepts: concepts/index.md
@@ -99,9 +100,16 @@ markdown_extensions:
   - admonition
   - pymdownx.details
   - attr_list
+  - mkdocs-click
 plugins:
   - search
   - mkdocs-jupyter
+  # - mkdocstrings:
+  #     default_handler: python
+  #     options:
+  #       preload_modules:
+  #       - docling
+  #       - docling_core
 
 extra_css:
   - stylesheets/extra.css
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -69,6 +69,7 @@ nbqa = "^1.9.0"
 [tool.poetry.group.docs.dependencies]
 mkdocs-material = "^9.5.40"
 mkdocs-jupyter = "^0.25.0"
+mkdocs-click = "^0.8.1"
 
 [tool.poetry.group.examples.dependencies]
 datasets = "^2.21.0"