tbi-readgen 0.0.21

A simple yet powerful Python project README.md generator.

ReadGen

This document was automatically generated by ReadGen as well!

tbi-readgen (0.0.21)

A simple yet powerful Python project README.md generator.

Features

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

# Recommendation, as it can be used globally.
$ pipx install tbi-readgen

Usage

CLI

# Overwrite README.md.
$ readgen -f

# Generate README.md without overwriting.
$ readgen

Configurable Project Information

Create a readgen.toml file in the project root:

[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:

# 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

Setup

git clone https://github.com/TaiwanBigdata/readgen.git
cd readgen
python -m venv env
source env/bin/activate  # Linux/Mac
pip install -e .

Directory Structure

readgen/
├── src/
│   └── readgen/
│       ├── utils/        # This folder is primarily used for storing commonly used utilities.
│       │   └── paths.py
│       ├── cli.py        # Handle command line interface (CLI) logic
│       ├── config.py
│       └── generator.py
├── LICENSE
├── pyproject.toml
├── readgen.toml
├── README.md
└── requirements.txt

License

This project is licensed under the MIT License.

---

This document was automatically generated by ReadGen.