readgen.toml

[ReadGen]
title = "ReadGen"
content = """
## This document was automatically generated by ReadGen as well!
### ${project.name} (${project.version})
${project.description}
"""

[Features]
content = """
1. Read project information from pyproject.toml
2. Read custom content from readgen.toml
    - Support variable substitution from pyproject.toml
    - Configure directory structure display with depth control
    - Toggle directory section display
3. Scan and filter project structure
    - Support glob patterns for excluding directories and files
    - Flexible depth control for directory display
    - Configurable file visibility
    - Support wildcard patterns for excluding directories and files
4. Extract comments from Python files for documentation
    - Read first-line comments for description
    - Support aligned comment display in directory tree
5. Generate a standardized README.md
    - Consistent formatting
    - Automatic section organization
    - Customizable content blocks
"""


[Installation]
content = """
```bash
# Recommendation, as it can be used globally.
$ pipx install tbi-readgen
```
"""

[Usage]
content = """
## CLI
```bash
# Overwrite README.md.
$ readgen -f

# Generate README.md without overwriting.
$ readgen
```

## Configurable Project Information
Create a `readgen.toml` file in the project root:
````toml
[Title]
title = "Method to overwrite [Title], with support for spaces."
content = "Content of the Title Block"

[Markdown]
content = \"\"\"
## This is a markdown block
1. Read project information from pyproject.toml
2. Read custom content from readgen.toml
3. Scan the project directory structure
4. Extract docstrings from `__init__.py` files in each folder
5. Generate a standardized README.md

```bash
$ pipx install tbi-readgen
```
\"\"\"

[Variables]
content = \"\"\"
Examples of variables from pyproject.toml:
- Use \\${project.version} to get the project version
- Use \\${project.name} to get the project name
\"\"\"

[License]
content = "This project is licensed under the \\${project.license} License."

[directory] # `directory` is a built-in method and will not be listed.
title = "Directory Structure" # Block names are customizable, allowing you to override the default "Directory Structure."
content = "The content displayed below the title."
enable = true # Default is true. Show the directory structure.
show_files = true # Default is true. Show files in the directory structure.
show_comments = true # Default is true. Show first-line comments in the directory structure.
max_depth = 1  # Optional. Specifies the maximum directory depth to display. Omit this line for no limit.

# Exclude patterns support various matching formats:
# Note: __init__.py files are always excluded from the file listing since their 
# comments are shown at the directory level. This behavior cannot be overridden.
exclude_patterns = [
    # 1. Directory specific patterns - must end with "/"
    "env/",               # Matches only 'env' directory
    "dist/",              # Matches only 'dist' directory
    
    # 2. Root-level file/directory matches
    "env",                # Matches file/directory named 'env' in root
    "file.txt",           # Matches specific file in root
    
    # 3. Recursive File extension wildcards
    "**/*.py",            # Matches all Python files at any depth
    "**/*.pyc",           # Matches all compiled Python files at any depth
    
    # 4. Recursive directory patterns
    "**/__pycache__/",    # Matches __pycache__ dirs at any depth
    "**/node_modules/",   # Matches node_modules dirs at any depth
    
    # 5. Path-specific depth patterns
    "app/web/static/*/*", # Matches files two levels deep in static
                          # e.g.: static/css/main.css - excluded
                          #       static/css          - not excluded
    
    # Common excludes
    "**/__pycache__/",
    ".git/",
    "build/",
    ".env*",              # Matches all .env files (.env, .env.dev)
    "*.egg-info/",
    "dist/",
    "env/",
]

[env] # `env` is a built-in method and will not be listed.
title = "Environment Variables" # Block names are customizable, allowing you to override the default "Environment Variables."
content = "The content displayed below the title."
enable = false # Default is true. Show the environment with description from the .env file.
env_file = ".env" # Default is ".env". The file to read the environment variables from.
````

# .env file

If block comments are placed above `.env` variables, they should follow this format:
```sh
# Project identification code used for service registration and resource management
PROJECT_ID=tbi-readgen
PROJECT_NAME=ReadGen

# Application runtime environment (dev/stage/prod)
APP_ENV=dev
APP_KEY=secret-key
```
will be displayed as:

### Environment Variables

Project identification code used for service registration and resource management

- `PROJECT_ID`
- `PROJECT_NAME`

Application runtime environment (dev/stage/prod)

- `APP_ENV`
- `APP_KEY`

# show_comments

If `show_comments` is set to `true`, first-line comments with a `#` prefix in the directory structure will be displayed.
```
readgen/
├── LICENSE
└── src/
    └── readgen/         # Comments from the `__init__.py` file will be displayed in the parent directory.
        ├── cli.py       # Comments with a `#` prefix at the beginning of the line will be displayed here.
        ├── config.py
        ...
```
"""

[Development]
content = """
### Setup
```bash
git clone https://github.com/TaiwanBigdata/readgen.git
cd readgen
python -m venv env
source env/bin/activate  # Linux/Mac
pip install -e .
```
"""


[env]
enable = false
env_file = ".env"

[directory]
enable = true
exclude_patterns = [
    ".cursorrules",
    ".env*",
    "**/.DS_Store",
    ".git/",
    ".gitignore",
    "env/",
    "**/__pycache__/",
    "*.egg-info/",
    "jupyterlab",
    "secrets",
    "build",
    "dist",
]
show_files = true
show_comments = true


[License]
content = "This project is licensed under the ${project.license} License."