Skip to content

usage.md

Latest commit

 

History

History
232 lines (164 loc) · 4.14 KB

usage.md

File metadata and controls

232 lines (164 loc) · 4.14 KB
Raw

Usage (Advanced Reference)

This page is the technical reference companion to:

  • docs/how-to-use.md (primary beginner-friendly guide)

Use this page when you need command variants, execution context choices, and workflow mapping.

Command model

doc-gen [OPTIONS] COMMAND [ARGS]...

Main commands:

  • init
  • structure generate
  • structure print
  • structure analyze

Global options:

  • --help
  • --version
  • --no-banner

Command Reference

init - Initialize Project

doc-gen init [--mode <mode>] [--force] [--ask] [--dry-run]

Supported modes:

  • all - Initialize everything
  • config - Initialize configuration only

Examples:

doc-gen init
doc-gen init --mode all
doc-gen init --mode config --ask
doc-gen init --mode all --force
doc-gen init --dry-run

structure generate - Generate Documentation

doc-gen structure generate [OPTIONS]

Supported options:

  • --profile [minimal|default|detailed]
  • --smart / --no-smart
  • --max-depth INTEGER
  • --show-files / --no-files
  • --output FILE
  • --dry-run / --no-dry-run

Examples:

doc-gen structure generate
doc-gen structure generate --profile minimal
doc-gen structure generate --smart
doc-gen structure generate --max-depth 2
doc-gen structure generate --show-files
doc-gen structure generate --output my-docs.md
doc-gen structure generate --output my-docs.md --dry-run

structure print - Print to Console

doc-gen structure print [OPTIONS]

Supported options:

  • Same as generate command
  • --dry-run / --no-dry-run

Examples:

doc-gen structure print
doc-gen structure print --smart
doc-gen structure print --max-depth 3
doc-gen structure print --dry-run

structure analyze - Analyze Project

doc-gen structure analyze [OPTIONS]

Examples:

doc-gen structure analyze
doc-gen structure analyze --smart
doc-gen structure analyze --dry-run

Execution Contexts

Local CLI

doc-gen structure generate

Python module mode

python -m doc_gen structure generate

Docker direct run

docker run -it --rm -w /workspace -v "${PWD}:/workspace" doc-gen structure generate

Docker Compose / Makefile workflows

Reference common automation from Makefile:

Local:

make l-generate
make l-generate-smart
make l-print
make l-print-smart
make l-analyze

Docker:

make d-generate
make d-generate-smart
make d-print
make d-print-smart
make d-analyze

Compose:

make c-generate
make c-generate-smart
make c-print
make c-print-smart
make c-analyze

Safety and Operational Notes

Recommended sequence:

  1. Initialize configuration (if needed) (doc-gen init)
  2. Run print command first to preview
  3. Generate documentation

Example:

doc-gen init
doc-gen structure print
doc-gen structure generate

For a non-mutating generation preview, run:

doc-gen structure generate --dry-run

Troubleshooting Quick Checks

  1. Verify command is available: 
    doc-gen --help
  2. Verify target directory exists
  3. Retry with debug (if available): 
    doc-gen structure generate --help
  4. Confirm config exists:
    • .projectstructure.toml

Exit Behavior

  • Success: exit code 0
  • Failure conditions: non-zero exit
  • Known configuration, target, structure, and filesystem failures include a concise reason and suggested correction.
  • Unexpected implementation details and Python tracebacks are hidden from normal output. Retry with global --debug and inspect the configured log file for technical diagnostics.
  • The error boundary does not weaken initialization or generated-output --dry-run safety.

See Also

  • Beginner guide: docs/how-to-use.md
  • Commands detail: docs/user-guide/commands.md
  • Configuration: docs/configuration.md
  • Dry-run safety: docs/dry-run.md
  • Installation: docs/installation.md