66 lines
1.6 KiB
Python
66 lines
1.6 KiB
Python
"""
|
|
# doc-forge
|
|
|
|
`doc-forge` is a renderer-agnostic Python documentation compiler designed for
|
|
speed, flexibility, and beautiful output. It decouples the introspection of
|
|
your code from the rendering process, allowing you to generate documentation
|
|
for various platforms (starting with MkDocs) from a single internal models.
|
|
|
|
## Installation
|
|
|
|
Install using `pip` with the optional `mkdocs` dependencies for a complete setup:
|
|
|
|
```bash
|
|
pip install doc-forge
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
1. **Generate Markdown Sources**:
|
|
Introspect your package and create ready-to-use Markdown files:
|
|
```bash
|
|
doc-forge generate --module my_package --docs-dir docs
|
|
```
|
|
|
|
2. **Define Navigation**:
|
|
Create a `docforge.nav.yml` to organize your documentation:
|
|
```yaml
|
|
home: my_package/index.md
|
|
groups:
|
|
Core API:
|
|
- my_package/core/*.md
|
|
Utilities:
|
|
- my_package/utils.md
|
|
```
|
|
|
|
3. **Generate MkDocs Configuration**:
|
|
```bash
|
|
doc-forge mkdocs --site-name "My Awesome Docs"
|
|
```
|
|
|
|
4. **Preview**:
|
|
```bash
|
|
doc-forge serve
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
- `docforge.loaders`: Introspects source code using static analysis (`griffe`).
|
|
- `docforge.models`: The internal representation of your project, modules, and objects.
|
|
- `docforge.renderers`: Converters that turn the models into physical files.
|
|
- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.
|
|
"""
|
|
|
|
from .loaders import GriffeLoader, discover_module_paths
|
|
from .renderers import MkDocsRenderer
|
|
from .cli import main
|
|
from . import models
|
|
|
|
__all__ = [
|
|
"GriffeLoader",
|
|
"discover_module_paths",
|
|
"MkDocsRenderer",
|
|
"models",
|
|
"main",
|
|
]
|