Fix CLI doc option_description errors in tests and build script (#2846)

Author: koxudaxi

docs/cli-reference/general-options.md

@@ -17,8 +17,8 @@
 | [`--ignore-pyproject`](#ignore-pyproject) | Ignore pyproject.toml configuration file. |
 | [`--module-split-mode`](#module-split-mode) | Split generated models into separate files, one per model cl... |
 | [`--shared-module-name`](#shared-module-name) | Customize the name of the shared module for deduplicated mod... |
-| [`--watch`](#watch) | Watch mode cannot be used with --check mode. |
-| [`--watch-delay`](#watch-delay) | Watch mode starts file watcher and handles clean exit. |
+| [`--watch`](#watch) | Watch input file(s) for changes and regenerate output automa... |
+| [`--watch-delay`](#watch-delay) | Set debounce delay in seconds for watch mode. |
 
 ---
 
@@ -1905,11 +1905,12 @@ Note: This option only affects modular output with tree-level model reuse.
 
 ## `--watch` {#watch}
 
-Watch mode cannot be used with --check mode.
+Watch input file(s) for changes and regenerate output automatically.
 
-The `--watch` flag enables file watching for automatic regeneration.
-It cannot be combined with `--check` since check mode requires a single
-comparison, not continuous watching.
+The `--watch` flag enables continuous file monitoring mode. When enabled,
+datamodel-codegen watches the input file or directory for changes and
+automatically regenerates the output whenever changes are detected.
+Press Ctrl+C to stop watching.
 
 !!! tip "Usage"
 
@@ -1919,6 +1920,14 @@ comparison, not continuous watching.
 
     1. :material-arrow-left: `--watch` - the option documented here
 
+!!! warning "Requires extra dependency"
+
+    The watch feature requires the `watch` extra:
+
+    ```bash
+    pip install 'datamodel-code-generator[watch]'
+    ```
+
 ??? example "Examples"
 
     === "JSON Schema"
@@ -1972,12 +1981,14 @@ comparison, not continuous watching.
 
 ## `--watch-delay` {#watch-delay}
 
-Watch mode starts file watcher and handles clean exit.
+Set debounce delay in seconds for watch mode.
+
+The `--watch-delay` option configures the debounce interval (default: 0.5 seconds)
+for watch mode. This prevents multiple regenerations when files are rapidly
+modified in succession. The delay ensures that after the last file change,
+the generator waits the specified time before regenerating.
 
-The `--watch` flag starts a file watcher that monitors the input file
-or directory for changes. The `--watch-delay` option sets the debounce
-delay in seconds (default: 0.5) to prevent multiple regenerations for
-rapid file changes. Press Ctrl+C to stop watching.
+**Related:** [`--watch`](general-options.md#watch)
 
 !!! tip "Usage"
 

docs/cli-reference/quick-reference.md

@@ -45,7 +45,7 @@ datamodel-codegen [OPTIONS]
 | [`--use-generic-container-types`](typing-customization.md#use-generic-container-types) | Use generic container types (Sequence, Mapping) for type hinting. |
 | [`--use-non-positive-negative-number-constrained-types`](typing-customization.md#use-non-positive-negative-number-constrained-types) | Use NonPositive/NonNegative types for number constraints. |
 | [`--use-pendulum`](typing-customization.md#use-pendulum) | Use pendulum types for date/time fields instead of datetime module. |
-| [`--use-root-model-type-alias`](typing-customization.md#use-root-model-type-alias) | Generate RootModel as type alias format for better mypy support (issue #1903). |
+| [`--use-root-model-type-alias`](typing-customization.md#use-root-model-type-alias) | Generate RootModel as type alias format for better mypy support. |
 | [`--use-specialized-enum`](typing-customization.md#use-specialized-enum) | Generate StrEnum/IntEnum for string/integer enums (Python 3.11+). |
 | [`--use-standard-collections`](typing-customization.md#use-standard-collections) | Use built-in dict/list instead of typing.Dict/List. |
 | [`--use-standard-primitive-types`](typing-customization.md#use-standard-primitive-types) | Use Python standard library types for string formats instead of str. |
@@ -173,15 +173,15 @@ datamodel-codegen [OPTIONS]
 | [`--ignore-pyproject`](general-options.md#ignore-pyproject) | Ignore pyproject.toml configuration file. |
 | [`--module-split-mode`](general-options.md#module-split-mode) | Split generated models into separate files, one per model class. |
 | [`--shared-module-name`](general-options.md#shared-module-name) | Customize the name of the shared module for deduplicated models. |
-| [`--watch`](general-options.md#watch) | Watch mode cannot be used with --check mode. |
-| [`--watch-delay`](general-options.md#watch-delay) | Watch mode starts file watcher and handles clean exit. |
+| [`--watch`](general-options.md#watch) | Watch input file(s) for changes and regenerate output automatically. |
+| [`--watch-delay`](general-options.md#watch-delay) | Set debounce delay in seconds for watch mode. |
 
 ### 📝 Utility Options
 
 | Option | Description |
 |--------|-------------|
 | [`--debug`](utility-options.md#debug) | Show debug messages during code generation |
-| [`--generate-prompt`](utility-options.md#generate-prompt) |  |
+| [`--generate-prompt`](utility-options.md#generate-prompt) | Generate a prompt for consulting LLMs about CLI options |
 | [`--help`](utility-options.md#help) | Show help message and exit |
 | [`--no-color`](utility-options.md#no-color) | Disable colorized output |
 | [`--profile`](utility-options.md#profile) | Use a named profile from pyproject.toml |
@@ -239,7 +239,7 @@ All options sorted alphabetically:
 - [`--formatters`](template-customization.md#formatters) - Specify code formatters to apply to generated output.
 - [`--frozen-dataclasses`](model-customization.md#frozen-dataclasses) - Generate frozen dataclasses with optional keyword-only field...
 - [`--generate-cli-command`](general-options.md#generate-cli-command) - Generate CLI command from pyproject.toml configuration.
-- [`--generate-prompt`](utility-options.md#generate-prompt) - 
+- [`--generate-prompt`](utility-options.md#generate-prompt) - Generate a prompt for consulting LLMs about CLI options
 - [`--generate-pyproject-config`](general-options.md#generate-pyproject-config) - Generate pyproject.toml configuration from CLI arguments.
 - [`--help`](utility-options.md#help) - Show help message and exit
 - [`--http-headers`](general-options.md#http-headers) - Fetch schema from URL with custom HTTP headers.
@@ -325,6 +325,6 @@ All options sorted alphabetically:
 - [`--use-unique-items-as-set`](typing-customization.md#use-unique-items-as-set) - Generate set types for arrays with uniqueItems constraint.
 - [`--validation`](openapi-only-options.md#validation) - Enable validation constraints (deprecated, use --field-const...
 - [`--version`](utility-options.md#version) - Show program version and exit
-- [`--watch`](general-options.md#watch) - Watch mode cannot be used with --check mode.
-- [`--watch-delay`](general-options.md#watch-delay) - Watch mode starts file watcher and handles clean exit.
+- [`--watch`](general-options.md#watch) - Watch input file(s) for changes and regenerate output automa...
+- [`--watch-delay`](general-options.md#watch-delay) - Set debounce delay in seconds for watch mode.
 - [`--wrap-string-literal`](template-customization.md#wrap-string-literal) - Wrap long string literals across multiple lines.

docs/cli-reference/typing-customization.md

@@ -3305,7 +3305,10 @@ working with the pendulum library for enhanced timezone and date handling.
 
 ## `--use-root-model-type-alias` {#use-root-model-type-alias}
 
-Generate RootModel as type alias format for better mypy support (issue #1903).
+Generate RootModel as type alias format for better mypy support.
+
+When enabled, root models with simple types are generated as type aliases
+instead of class definitions, improving mypy type inference.
 
 !!! tip "Usage"
 

docs/cli-reference/utility-options.md

@@ -5,7 +5,7 @@
 | Option | Description |
 |--------|-------------|
 | [`--debug`](#debug) | Show debug messages during code generation |
-| [`--generate-prompt`](#generate-prompt) |  |
+| [`--generate-prompt`](#generate-prompt) | Generate a prompt for consulting LLMs about CLI options |
 | [`--help`](#help) | Show help message and exit |
 | [`--no-color`](#no-color) | Disable colorized output |
 | [`--profile`](#profile) | Use a named profile from pyproject.toml |
@@ -46,7 +46,7 @@ Outputs a formatted prompt containing your current options, all available
 options by category, and full help text. Pipe to CLI LLM tools or copy
 to clipboard for web-based LLM chats.
 
-**See also:** [LLM Integration](../../llm-integration.md) for detailed usage examples
+**See also:** [LLM Integration](../llm-integration.md) for detailed usage examples
 
 !!! tip "Usage"
 
@@ -139,7 +139,7 @@ Use a named profile from pyproject.toml configuration.
 Profiles allow you to define multiple named configurations in your pyproject.toml
 file. Each profile can override the default settings with its own set of options.
 
-**Related:** [pyproject.toml Configuration](../../pyproject_toml.md)
+**Related:** [pyproject.toml Configuration](../pyproject_toml.md)
 
 !!! tip "Usage"
 

scripts/build_cli_docs.py

@@ -179,6 +179,7 @@ def get_unique_schema_types(self) -> list[str]:
     "--debug": "Show debug messages during code generation",
     "--profile": "Use a named profile from pyproject.toml",
     "--no-color": "Disable colorized output",
+    "--generate-prompt": "Generate a prompt for consulting LLMs about CLI options",
 }
 
 # Regex pattern for detecting MkDocs Material admonitions in docstrings
@@ -907,6 +908,9 @@ def generate_manual_docs_section(manual_docs: dict[str, str]) -> str:
 
     for option in sorted(manual_docs.keys()):
         content = manual_docs[option]
+        # Adjust relative paths: manual docs are in manual/ subdirectory,
+        # but utility-options.md is in cli-reference/, so ../../ becomes ../
+        content = content.replace("](../../", "](../")
         md += content
         if not content.endswith("\n"):
             md += "\n"

src/datamodel_code_generator/prompt_data.py

@@ -119,7 +119,7 @@
     "--use-one-literal-as-default": "Use single literal value as default when enum has only one option.",
     "--use-operation-id-as-name": "Use OpenAPI operationId as the generated function/class name.",
     "--use-pendulum": "Use pendulum types for date/time fields instead of datetime module.",
-    "--use-root-model-type-alias": "Generate RootModel as type alias format for better mypy support (issue #1903).",
+    "--use-root-model-type-alias": "Generate RootModel as type alias format for better mypy support.",
     "--use-schema-description": "Use schema description as class docstring.",
     "--use-serialize-as-any": "Wrap fields with subtypes in Pydantic's SerializeAsAny.",
     "--use-specialized-enum": "Generate StrEnum/IntEnum for string/integer enums (Python 3.11+).",
@@ -133,7 +133,7 @@
     "--use-union-operator": "Use | operator for Union types (PEP 604).",
     "--use-unique-items-as-set": "Generate set types for arrays with uniqueItems constraint.",
     "--validation": "Enable validation constraints (deprecated, use --field-constraints).",
-    "--watch": "Watch mode cannot be used with --check mode.",
-    "--watch-delay": "Watch mode starts file watcher and handles clean exit.",
+    "--watch": "Watch input file(s) for changes and regenerate output automatically.",
+    "--watch-delay": "Set debounce delay in seconds for watch mode.",
     "--wrap-string-literal": "Wrap long string literals across multiple lines.",
 }

tests/main/jsonschema/test_main_jsonschema.py

@@ -5485,7 +5485,11 @@ def test_main_jsonschema_empty_items_array(output_file: Path) -> None:
 
 @pytest.mark.cli_doc(
     options=["--aliases"],
-    option_description="""Test hierarchical aliases with scoped format (ClassName.field).""",
+    option_description="""Apply custom field and class name aliases from JSON file.
+
+The `--aliases` option allows renaming fields and classes via a JSON mapping file,
+providing fine-grained control over generated names independent of schema definitions.
+Supports scoped format (ClassName.field) for hierarchical aliasing.""",
     input_schema="jsonschema/hierarchical_aliases.json",
     cli_args=["--aliases", "aliases/hierarchical_aliases_scoped.json"],
     golden_output="jsonschema/jsonschema_hierarchical_aliases_scoped.py",
@@ -5960,12 +5964,11 @@ def test_main_jsonschema_ref_with_additional_keywords(output_dir: Path) -> None:
 )
 @pytest.mark.cli_doc(
     options=["--output-model-type"],
-    option_description="""Test reserved field name handling across model types (Issue #1833).
+    option_description="""Select the output model type (Pydantic v1/v2, dataclasses, TypedDict, msgspec).
 
-This demonstrates how 'schema' field is handled:
-- TypedDict: not renamed (schema is not reserved)
-- dataclass: not renamed (schema is not reserved)
-- Pydantic: renamed to 'schema_' with alias (BaseModel.schema conflicts)""",
+The `--output-model-type` flag specifies which Python data model framework to use.
+Each model type has different handling for reserved field names like 'schema':
+TypedDict and dataclass preserve the name, while Pydantic renames with alias.""",
     input_schema="jsonschema/reserved_field_name_schema.json",
     cli_args=["--target-python-version", "3.11"],
     model_outputs={
@@ -6833,7 +6836,10 @@ def test_main_parent_scoped_naming_backward_compat(output_file: Path) -> None:
 
 @pytest.mark.cli_doc(
     options=["--use-root-model-type-alias"],
-    option_description="""Generate RootModel as type alias format for better mypy support (issue #1903).""",
+    option_description="""Generate RootModel as type alias format for better mypy support.
+
+When enabled, root models with simple types are generated as type aliases
+instead of class definitions, improving mypy type inference.""",
     input_schema="jsonschema/root_model_type_alias.json",
     cli_args=["--use-root-model-type-alias", "--output-model-type", "pydantic_v2.BaseModel"],
     golden_output="jsonschema/root_model_type_alias.py",

tests/main/test_main_watch.py

@@ -16,14 +16,24 @@
 
 @pytest.mark.cli_doc(
     options=["--watch"],
-    option_description="""Watch mode cannot be used with --check mode.
+    option_description="""Watch input file(s) for changes and regenerate output automatically.
 
-The `--watch` flag enables file watching for automatic regeneration.
-It cannot be combined with `--check` since check mode requires a single
-comparison, not continuous watching.""",
+The `--watch` flag enables continuous file monitoring mode. When enabled,
+datamodel-codegen watches the input file or directory for changes and
+automatically regenerates the output whenever changes are detected.
+Press Ctrl+C to stop watching.
+
+!!! warning "Requires extra dependency"
+
+    The watch feature requires the `watch` extra:
+
+    ```bash
+    pip install 'datamodel-code-generator[watch]'
+    ```""",
     input_schema="jsonschema/person.json",
     cli_args=["--watch", "--check"],
     expected_stdout="Error: --watch and --check cannot be used together",
+    primary=True,
 )
 def test_watch_with_check_error(output_file: Path) -> None:
     """Watch mode cannot be used with --check mode.
@@ -48,10 +58,11 @@ def test_watch_with_check_error(output_file: Path) -> None:
 
 @pytest.mark.cli_doc(
     options=["--watch"],
-    option_description="""Watch mode requires a file path input, not a URL.
+    option_description="""Watch input file(s) for changes and regenerate output automatically.
 
-The `--watch` flag monitors local files for changes. It cannot be used
-with `--url` since remote URLs cannot be watched for changes.""",
+The `--watch` flag monitors local files for changes. It requires a local file
+path via `--input` and cannot be used with `--url` since remote URLs cannot
+be watched for changes.""",
     cli_args=["--watch", "--url", "https://example.com/schema.json"],
     expected_stdout="Error: --watch requires --input file path",
 )
@@ -122,12 +133,14 @@ def test_get_watchfiles_success() -> None:
 
 @pytest.mark.cli_doc(
     options=["--watch", "--watch-delay"],
-    option_description="""Watch mode starts file watcher and handles clean exit.
+    option_description="""Set debounce delay in seconds for watch mode.
+
+The `--watch-delay` option configures the debounce interval (default: 0.5 seconds)
+for watch mode. This prevents multiple regenerations when files are rapidly
+modified in succession. The delay ensures that after the last file change,
+the generator waits the specified time before regenerating.
 
-The `--watch` flag starts a file watcher that monitors the input file
-or directory for changes. The `--watch-delay` option sets the debounce
-delay in seconds (default: 0.5) to prevent multiple regenerations for
-rapid file changes. Press Ctrl+C to stop watching.""",
+**Related:** [`--watch`](general-options.md#watch)""",
     input_schema="jsonschema/person.json",
     cli_args=["--watch", "--watch-delay", "1.5"],
     expected_stdout="Watching",