Add auto-generated CLI reference documentation from test cases (#2673)

* docs: add initial CLI documentation structure and update related files

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* docs: exclude CLI reference from codespell checks

* docs: remove redundant code in CLI documentation coverage test

* docs: add coverage markers to functions and classes in CLI-related files

* docs: enhance CLI documentation generation and coverage reporting

* docs: update CLI reference documentation

🤖 Generated by GitHub Actions

* docs: add CLI documentation check job to GitHub Actions workflow

* docs: add test for get_canonical_option and refine help text validation

* docs: improve CLI argument formatting and fix test cases

* docs: fix CLI usage examples for consistency and correctness

* docs: enhance CLI documentation generation error reporting and add formatter kwargs

* docs: update formatter kwargs path and add empty JSON file

* docs: enhance error reporting in CLI documentation generation

* docs: update CLI usage examples for consistency and correctness

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

.github/workflows/cli-docs.yaml

@@ -0,0 +1,52 @@
+name: Update CLI Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'tests/main/**'
+      - 'tests/test_main_kr.py'
+      - 'src/datamodel_code_generator/cli_options.py'
+      - 'scripts/build_cli_docs.py'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'tests/main/**'
+      - 'tests/test_main_kr.py'
+      - 'src/datamodel_code_generator/cli_options.py'
+      - 'scripts/build_cli_docs.py'
+
+permissions:
+  contents: write
+
+jobs:
+  update-cli-docs:
+    if: github.event_name == 'push' || !github.event.pull_request.head.repo.fork
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.head_ref || github.ref }}
+          token: ${{ secrets.PAT }}
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install tox
+        run: uv tool install --python-preference only-managed --python 3.13 tox --with tox-uv
+      - name: Setup environment
+        run: tox run -vv --notest --skip-missing-interpreters false -e cli-docs
+        env:
+          UV_PYTHON_PREFERENCE: "only-managed"
+      - name: Collect CLI doc metadata
+        run: .tox/cli-docs/bin/pytest --collect-cli-docs -p no:xdist -q
+      - name: Build CLI docs
+        run: .tox/cli-docs/bin/python scripts/build_cli_docs.py
+      - name: Commit and push if changed
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/cli-reference/
+          git diff --staged --quiet || git commit -m "docs: update CLI reference documentation
+
+          🤖 Generated by GitHub Actions"
+          git push

.github/workflows/codespell.yaml

@@ -27,3 +27,4 @@ jobs:
         uses: codespell-project/actions-codespell@v2
         with:
           exclude_file: CODE_OF_CONDUCT.md
+          skip: ./docs/cli-reference

.gitignore

@@ -5,3 +5,5 @@ coverage.xml
 .coverage
 .idea/
 .vscode/
+site/
+tests/cli_doc/.cli_doc_collection.json

.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
   - id: codespell
     additional_dependencies:
     - tomli
-    exclude: "^tests/|^CODE_OF_CONDUCT.md"
+    exclude: "^tests/|^CODE_OF_CONDUCT.md|^docs/cli-reference/"
 - repo: local
   hooks:
   - id: readme

README.md

@@ -329,6 +329,8 @@ This method needs the [http extra option](#http-extra-option)
 
 ## All Command Options
 
+> 📖 **For detailed documentation with examples, see the [CLI Reference](https://koxudaxi.github.io/datamodel-code-generator/cli-reference/).**
+
 The `datamodel-codegen` command:
 
 <!-- start command help -->

docs/cli-reference/base-options.md

@@ -0,0 +1,301 @@
+# Base Options
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| [`--encoding`](#encoding) | Specify character encoding for input and output files. |
+| [`--input`](#input) | Specify the input schema file path. |
+| [`--input-file-type`](#input-file-type) | Specify the input file type for code generation. |
+| [`--output`](#output) | Specify the destination path for generated Python code. |
+| [`--url`](#url) | Fetch schema from URL with custom HTTP headers. |
+
+---
+
+## `--encoding` {#encoding}
+
+Specify character encoding for input and output files.
+
+The `--encoding` flag sets the character encoding used when reading
+the schema file and writing the generated Python code. This is useful
+for schemas containing non-ASCII characters (e.g., Japanese, Chinese).
+Default is utf-8.
+
+!!! tip "Usage"
+
+    ```bash
+    datamodel-codegen --input schema.json --encoding utf-8 # (1)!
+    ```
+
+    1. :material-arrow-left: `--encoding` - the option documented here
+
+??? example "Input Schema"
+
+    ```json
+    {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "title": "日本語Model",
+      "description": "モデルの説明文",
+      "type": "object",
+      "properties": {
+        "名前": {
+          "type": "string",
+          "description": "ユーザー名"
+        },
+        "年齢": {
+          "type": "integer"
+        }
+      }
+    }
+    ```
+
+??? example "Output"
+
+    ```python
+    # generated by datamodel-codegen:
+    #   filename:  encoding_test.json
+    #   timestamp: 2019-07-26T00:00:00+00:00
+    
+    from __future__ import annotations
+    
+    from typing import Optional
+    
+    from pydantic import BaseModel, Field
+    
+    
+    class 日本語Model(BaseModel):
+        名前: Optional[str] = Field(None, description='ユーザー名')
+        年齢: Optional[int] = None
+    ```
+
+---
+
+## `--input` {#input}
+
+Specify the input schema file path.
+
+The `--input` flag specifies the path to the schema file (JSON Schema,
+OpenAPI, GraphQL, etc.). Multiple input files can be specified to merge
+schemas. Required unless using `--url` to fetch schema from a URL.
+
+!!! tip "Usage"
+
+    ```bash
+    datamodel-codegen --input schema.json --input pet_simple.json --output output.py # (1)!
+    ```
+
+    1. :material-arrow-left: `--input` - the option documented here
+
+??? example "Input Schema"
+
+    ```json
+    {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "title": "Pet",
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer"
+        },
+        "name": {
+          "type": "string"
+        },
+        "tag": {
+          "type": "string"
+        }
+      }
+    }
+    ```
+
+??? example "Output"
+
+    ```python
+    # generated by datamodel-codegen:
+    #   filename:  pet_simple.json
+    #   timestamp: 2019-07-26T00:00:00+00:00
+    
+    from __future__ import annotations
+    
+    from typing import Optional
+    
+    from pydantic import BaseModel
+    
+    
+    class Pet(BaseModel):
+        id: Optional[int] = None
+        name: Optional[str] = None
+        tag: Optional[str] = None
+    ```
+
+---
+
+## `--input-file-type` {#input-file-type}
+
+Specify the input file type for code generation.
+
+The `--input-file-type` flag explicitly sets the input format when it cannot
+be auto-detected from the file extension. Supported types: openapi, jsonschema,
+json, yaml, csv, graphql.
+
+!!! tip "Usage"
+
+    ```bash
+    datamodel-codegen --input schema.json --input-file-type json # (1)!
+    ```
+
+    1. :material-arrow-left: `--input-file-type` - the option documented here
+
+??? example "Input Schema"
+
+    ```json
+    {
+      "Pet": {
+        "name": "dog",
+        "age": 2
+      }
+    }
+    ```
+
+??? example "Output"
+
+    ```python
+    # generated by datamodel-codegen:
+    #   filename:  pet.json
+    #   timestamp: 2019-07-26T00:00:00+00:00
+    
+    from __future__ import annotations
+    
+    from pydantic import BaseModel
+    
+    
+    class Pet(BaseModel):
+        name: str
+        age: int
+    
+    
+    class Model(BaseModel):
+        Pet: Pet
+    ```
+
+---
+
+## `--output` {#output}
+
+Specify the destination path for generated Python code.
+
+The `--output` flag specifies where to write the generated Python code.
+It can be either a file path (single-file output) or a directory path
+(multi-file output for modular schemas). If omitted, the generated code
+is written to stdout.
+
+!!! tip "Usage"
+
+    ```bash
+    datamodel-codegen --input schema.json --input pet_simple.json --output output.py # (1)!
+    ```
+
+    1. :material-arrow-left: `--output` - the option documented here
+
+??? example "Input Schema"
+
+    ```json
+    {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "title": "Pet",
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer"
+        },
+        "name": {
+          "type": "string"
+        },
+        "tag": {
+          "type": "string"
+        }
+      }
+    }
+    ```
+
+??? example "Output"
+
+    ```python
+    # generated by datamodel-codegen:
+    #   filename:  pet_simple.json
+    #   timestamp: 2019-07-26T00:00:00+00:00
+    
+    from __future__ import annotations
+    
+    from typing import Optional
+    
+    from pydantic import BaseModel
+    
+    
+    class Pet(BaseModel):
+        id: Optional[int] = None
+        name: Optional[str] = None
+        tag: Optional[str] = None
+    ```
+
+---
+
+## `--url` {#url}
+
+Fetch schema from URL with custom HTTP headers.
+
+The `--url` flag specifies a remote URL to fetch the schema from instead of
+a local file. The `--http-headers` flag adds custom HTTP headers to the request,
+useful for authentication (e.g., Bearer tokens) or custom API requirements.
+Format: `HeaderName:HeaderValue`.
+
+!!! tip "Usage"
+
+    ```bash
+    datamodel-codegen --input schema.json --url https://api.example.com/schema.json --http-headers "Authorization:Bearer token" # (1)!
+    ```
+
+    1. :material-arrow-left: `--url` - the option documented here
+
+??? example "Input Schema"
+
+    ```json
+    {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "title": "Pet",
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer"
+        },
+        "name": {
+          "type": "string"
+        },
+        "tag": {
+          "type": "string"
+        }
+      }
+    }
+    ```
+
+??? example "Output"
+
+    ```python
+    # generated by datamodel-codegen:
+    #   filename:  https://api.example.com/schema.json
+    #   timestamp: 2019-07-26T00:00:00+00:00
+    
+    from __future__ import annotations
+    
+    from typing import Optional
+    
+    from pydantic import BaseModel
+    
+    
+    class Pet(BaseModel):
+        id: Optional[int] = None
+        name: Optional[str] = None
+        tag: Optional[str] = None
+    ```
+
+---
+