| Name | tbi-readgen JSON |
| Version |
0.0.18
JSON |
| download |
| home_page | None |
| Summary | A simple yet powerful Python project README.md generator. |
| upload_time | 2024-12-15 22:45:44 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
cli
generator
markdown
readme
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ReadGen
## This document was automatically generated by ReadGen as well!
### tbi-readgen (0.0.18)
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.
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
### 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 .
```
# 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
├── .gitignore
├── 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](https://github.com/TaiwanBigdata/readgen).
Raw data
{
"_id": null,
"home_page": null,
"name": "tbi-readgen",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cli, generator, markdown, readme",
"author": null,
"author_email": "Albert Liu <dreamerhyde@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/3e/bdaec0df15bebb8a4b648416dd07c4fa5469c99be902f8fb5f278b82ebcb/tbi_readgen-0.0.18.tar.gz",
"platform": null,
"description": "# ReadGen\n\n## This document was automatically generated by ReadGen as well!\n### tbi-readgen (0.0.18)\nA simple yet powerful Python project README.md generator.\n\n\n# Features\n\n1. Read project information from pyproject.toml\n2. Read custom content from readgen.toml\n - Support variable substitution from pyproject.toml\n - Configure directory structure display with depth control\n - Toggle directory section display\n3. Scan and filter project structure\n - Support glob patterns for excluding directories and files\n - Flexible depth control for directory display\n - Configurable file visibility\n - Support wildcard patterns for excluding directories and files\n4. Extract comments from Python files for documentation\n - Read first-line comments for description\n - Support aligned comment display in directory tree\n5. Generate a standardized README.md\n - Consistent formatting\n - Automatic section organization\n - Customizable content blocks\n\n\n# Installation\n\n```bash\n$ pip install tbi-readgen\n\n# Recommendation, as it can be used globally.\n$ pipx install tbi-readgen\n```\n\n\n# Usage\n\n## CLI\n```bash\n$ readgen\n\n# Overwrite README.md.\n$ readgen -f\n```\n\n## Configurable Project Information\nCreate a `readgen.toml` file in the project root:\n````toml\n[Title]\ntitle = \"Method to overwrite [Title], with support for spaces.\"\ncontent = \"Content of the Title Block\"\n\n[Markdown]\ncontent = \"\"\"\n## This is a markdown block\n1. Read project information from pyproject.toml\n2. Read custom content from readgen.toml\n3. Scan the project directory structure\n4. Extract docstrings from `__init__.py` files in each folder\n5. Generate a standardized README.md\n\n```bash\n$ pipx install tbi-readgen\n```\n\"\"\"\n\n[Variables]\ncontent = \"\"\"\nExamples of variables from pyproject.toml:\n- Use ${project.version} to get the project version\n- Use ${project.name} to get the project name\n\"\"\"\n\n[License]\ncontent = \"This project is licensed under the ${project.license} License.\"\n\n[directory] # `directory` is a built-in method and will not be listed.\ntitle = \"Directory Structure\" # Block names are customizable, allowing you to override the default \"Directory Structure.\"\ncontent = \"The content displayed below the title.\"\nenable = true # Default is true. Show the directory structure.\nshow_files = true # Default is true. Show files in the directory structure.\nshow_comments = true # Default is true. Show first-line comments in the directory structure.\nmax_depth = 1 # Optional. Specifies the maximum directory depth to display. Omit this line for no limit.\n\n# Exclude patterns support various matching formats:\n# Note: __init__.py files are always excluded from the file listing since their \n# comments are shown at the directory level. This behavior cannot be overridden.\nexclude_patterns = [\n # 1. Directory specific patterns - must end with \"/\"\n \"env/\", # Matches only 'env' directory\n \"dist/\", # Matches only 'dist' directory\n \n # 2. Root-level file/directory matches\n \"env\", # Matches file/directory named 'env' in root\n \"file.txt\", # Matches specific file in root\n \n # 3. Recursive File extension wildcards\n \"**/*.py\", # Matches all Python files at any depth\n \"**/*.pyc\", # Matches all compiled Python files at any depth\n \n # 4. Recursive directory patterns\n \"**/__pycache__/\", # Matches __pycache__ dirs at any depth\n \"**/node_modules/\", # Matches node_modules dirs at any depth\n \n # 5. Path-specific depth patterns\n \"app/web/static/*/*\", # Matches files two levels deep in static\n # e.g.: static/css/main.css - excluded\n # static/css - not excluded\n \n # Common excludes\n \"**/__pycache__/\",\n \".git/\",\n \"build/\",\n \".env*\", # Matches all .env files (.env, .env.dev)\n \"*.egg-info/\",\n \"dist/\",\n \"env/\",\n]\n\n[env] # `env` is a built-in method and will not be listed.\ntitle = \"Environment Variables\" # Block names are customizable, allowing you to override the default \"Environment Variables.\"\ncontent = \"The content displayed below the title.\"\nenable = false # Default is true. Show the environment with description from the .env file.\nenv_file = \".env\" # Default is \".env\". The file to read the environment variables from.\n````\n\n# .env file\n\nIf block comments are placed above `.env` variables, they should follow this format:\n```sh\n# Project identification code used for service registration and resource management\nPROJECT_ID=tbi-readgen\nPROJECT_NAME=ReadGen\n\n# Application runtime environment (dev/stage/prod)\nAPP_ENV=dev\nAPP_KEY=secret-key\n```\nwill be displayed as:\n\n### Environment Variables\n\nProject identification code used for service registration and resource management\n\n- `PROJECT_ID`\n- `PROJECT_NAME`\n\nApplication runtime environment (dev/stage/prod)\n\n- `APP_ENV`\n- `APP_KEY`\n\n# show_comments\n\nIf `show_comments` is set to `true`, first-line comments with a `#` prefix in the directory structure will be displayed.\n```\nreadgen/\n\u251c\u2500\u2500 LICENSE\n\u2514\u2500\u2500 src/\n \u2514\u2500\u2500 readgen/ # Comments from the `__init__.py` file will be displayed in the parent directory.\n \u251c\u2500\u2500 cli.py # Comments with a `#` prefix at the beginning of the line will be displayed here.\n \u251c\u2500\u2500 config.py\n ...\n```\n\n\n# Development\n\n### Setup\n```bash\ngit clone https://github.com/TaiwanBigdata/readgen.git\ncd readgen\npython -m venv env\nsource env/bin/activate # Linux/Mac\npip install -e .\n```\n\n\n# Directory Structure\n\n```\nreadgen/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 readgen/\n\u2502 \u251c\u2500\u2500 utils/ # This folder is primarily used for storing commonly used utilities.\n\u2502 \u2502 \u2514\u2500\u2500 paths.py\n\u2502 \u251c\u2500\u2500 cli.py # Handle command line interface (CLI) logic\n\u2502 \u251c\u2500\u2500 config.py\n\u2502 \u2514\u2500\u2500 generator.py\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 readgen.toml\n\u251c\u2500\u2500 README.md\n\u2514\u2500\u2500 requirements.txt\n```\n\n\n# License\n\nThis project is licensed under the MIT License.\n\n\n---\n> This document was automatically generated by [ReadGen](https://github.com/TaiwanBigdata/readgen).\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple yet powerful Python project README.md generator.",
"version": "0.0.18",
"project_urls": {
"Homepage": "https://github.com/TaiwanBigdata/readgen",
"Repository": "https://github.com/TaiwanBigdata/readgen.git"
},
"split_keywords": [
"cli",
" generator",
" markdown",
" readme"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e9a054c1a35151523b8d62b449225bfe39d98d42341d90590a656691c323ac6",
"md5": "9b1f31ee36da1ede3edfe6e226a25ad5",
"sha256": "110fb2c8cda1875f454393a107c6d935ced0434cffcd1399ec9afe98c4e0deb7"
},
"downloads": -1,
"filename": "tbi_readgen-0.0.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b1f31ee36da1ede3edfe6e226a25ad5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11681,
"upload_time": "2024-12-15T22:45:41",
"upload_time_iso_8601": "2024-12-15T22:45:41.747852Z",
"url": "https://files.pythonhosted.org/packages/0e/9a/054c1a35151523b8d62b449225bfe39d98d42341d90590a656691c323ac6/tbi_readgen-0.0.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a3ebdaec0df15bebb8a4b648416dd07c4fa5469c99be902f8fb5f278b82ebcb",
"md5": "bcfe4dbb10d9a33cd4c160549d8a50b1",
"sha256": "adc1eda2124d930ad98e56737d241c17518296a2b74162968f1be5027af75506"
},
"downloads": -1,
"filename": "tbi_readgen-0.0.18.tar.gz",
"has_sig": false,
"md5_digest": "bcfe4dbb10d9a33cd4c160549d8a50b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11054,
"upload_time": "2024-12-15T22:45:44",
"upload_time_iso_8601": "2024-12-15T22:45:44.107956Z",
"url": "https://files.pythonhosted.org/packages/4a/3e/bdaec0df15bebb8a4b648416dd07c4fa5469c99be902f8fb5f278b82ebcb/tbi_readgen-0.0.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 22:45:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TaiwanBigdata",
"github_project": "readgen",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "tbi-readgen"
}
