📦 Doc Gen

Doc Gen generates Markdown project trees, prints directory structures, and analyzes repository layout. Use profiles, smart mode, and explicit output paths to tailor the result.

The v0.1.0 project was named print_project_structure; the rename to Doc Gen is part of v1.0.0-rc.1, not a later stable-only change.

• 📂 Generate repository tree structure
• 📄 Generate Markdown at a configured or explicitly selected output path
• 🔎 Separate read-only structure printing and analysis commands
• 🧠 Smart mode (auto-detect project size & optimize output)
• 🎯 Profiles (minimal, default, detailed)
• ⚙️ Namespaced configuration in .config/doc_gen/config.toml
• 🎨 Colored CLI output (rich UI)
• ⚡ Fast and lightweight
• 🛡️ Explicit dry-run safety for initialization and generated output

Runtime compatibility is Python 3.9+; the standard development and container runtime is Python 3.14. Contributor formatting tools have their own newer Python requirements; use Python 3.14 for the complete development environment.

Choose a version already published in the target project's registry. In an activated virtual environment, replace the placeholders:

python -m pip install --index-url "https://gitlab.com/api/v4/projects/<project-id>/packages/pypi/simple" "doc-gen==<package-version>"
doc-gen --help

Use a deploy token with read_package_registry. Supply credentials through pip authentication, not committed files or shared command history. The package version is PEP 440: v1.0.0-rc.1 becomes 1.0.0rc1; v1.0.0 becomes 1.0.0. Use --index-url, not --extra-index-url; review GitLab package forwarding if dependencies must stay private.

See installation and registry guidance for authentication, other installation methods, and registry setup.

Create and activate a virtual environment, then install from the source root:

python -m pip install -e .
doc-gen --help

Preview initialization, then create the configuration when ready:

doc-gen init --dry-run
doc-gen init

Review .config/doc_gen/config.toml. Preview generation before writing output:

doc-gen structure generate . --output docs/project_structure.md --dry-run
doc-gen structure generate . --output docs/project_structure.md

The second command writes docs/project_structure.md. Without --output, the selected configuration or internal default determines the path.

• 📘 User Guide Overview
• 📖 CLI Commands Reference
• 📖 Makefile Commands Reference

• Installation → docs/user-guide/installation-methods.md
• Quickstart → docs/user-guide/quickstart.md

• Overview → docs/user-guide/overview.md
• Commands → docs/user-guide/commands.md
• Config → docs/configuration.md
• Smart Mode → docs/user-guide/smart-mode.md
• Examples → docs/usage.md

• CLI Reference → docs/user-guide/commands.md

• Setup → docs/developer-guide/getting-started.md
• Makefile → docs/developer-guide/make-workflow.md

• Architecture → docs/architecture/workflow.md

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

Preview any workflow without changing project output:

doc-gen init --dry-run
doc-gen structure generate --dry-run .
doc-gen structure print --dry-run .
doc-gen structure analyze --dry-run .

After doc-gen init, edit .config/doc_gen/config.toml:

[tool.doc-gen.cli.structure]
profile = "custom"
max_depth = 5
show_files = true
smart_mode = false

[tool.doc-gen.cli.structure.generate]
output_file = "docs/project_structure.md"

CLI options override configured values. --dry-run allows read-only discovery but prevents persistent generated output; diagnostic logs may still be written.

Automatically adjusts:

• depth
• file visibility
• directory collapsing

doc-gen structure generate --smart .

app/doc_gen/
├── cli/
├── config/
├── core/
│   ├── initialize/
│   └── structure/
├── services/
├── templates/
├── ui/
└── utils/

For the details, see full structure in project_structure.md.

The optional metadata sync script is source-checkout tooling, not an installed application command. Run it from this repository's root:

python scripts/repository/src/sync_metadata.py --dry-run

It reads [project].description and the separate [tool.devalltect.github].topics / [tool.devalltect.gitlab].topics tables in pyproject.toml. Package keywords are not repository topics.

Review GITHUB_REMOTES and GITLAB_REMOTES in the script: the current defaults are origin and backup. Each list contains fallback candidates; the first valid fetch URL selects one repository per provider. Both providers must resolve. This helper currently targets GitHub.com and GitLab.com.

Dry-run uses Python and read-only Git discovery; it does not call provider APIs. Live synchronization additionally needs authenticated gh and glab with access to update those repositories.

Before removing --dry-run, review the targets and metadata carefully: the live helper does not ask for confirmation, replaces the topic lists, and clears existing topics when a list is empty or missing. A failure can leave earlier updates applied; there is no cross-provider rollback.

Known follow-up: the script's docstring still shows the old path, and its GitHub topic-limit constant is 50 despite GitHub's maximum of 20 topics. Use the path above and keep the GitHub list within 20 until corrected. These issues and isolated test coverage are tracked in the TODO history.

Contributions, issues, and suggestions are welcome.

Before contributing, review: docs/developer-guide/

and: docs/architecture/

For the details, see CONTRIBUTING.md

See SECURITY.md

See CHANGELOG.md

See LICENSE for the licensing terms.

📧 Contact: [email protected]

Handcrafted with ❤️ by Devalltect / Rizky Fernandes