Metadata-Version: 2.3
Name: tbi-readgen
Version: 0.0.13
Summary: A README generator for Python projects
Project-URL: Homepage, https://github.com/TaiwanBigdata/readgen
Project-URL: Repository, https://github.com/TaiwanBigdata/readgen.git
Author-email: Albert Liu <dreamerhyde@gmail.com>
License: MIT
Keywords: cli,generator,markdown,readme
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# ReadGen

## This document was automatically generated by ReadGen as well!
### tbi-readgen (0.0.13)
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

```bash
$ pip install tbi-readgen

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


# Usage

## CLI
```bash
$ readgen

# Overwrite README.md.
$ readgen -f
```

## 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.
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:
```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 here.
        ├── cli.py       # Comments with a `#` prefix at the beginning of the line will be displayed here.
        ├── config.py
        ...
```


# Development

### 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 .
```


# 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](https://github.com/TaiwanBigdata/readgen).
