tbi-readgen 0.0.14

A simple yet powerful Python project README.md generator.

ReadGen

This document was automatically generated by ReadGen as well!

tbi-readgen (0.0.14)

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

$ pip install tbi-readgen

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

Usage

CLI

$ readgen

# Overwrite README.md.
$ readgen -f

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.
exclude_dirs = [".git", "env", "__pycache__", "build", "dist", "src/**/tests"] # Exclude directories from scanning. Supports wildcard patterns.
exclude_files = [".env*"] # Exclude files from scanning. Supports wildcard patterns.
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.

[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 here.
        ├── 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 .

License

This project is licensed under the MIT License.

Directory Structure

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

---

This document was automatically generated by ReadGen.