Metadata-Version: 2.4
Name: proj2md
Version: 0.1.0
Summary: Generate a comprehensive Markdown document for any project directory via CLI
Author-email: Thibaud Perrin <thibaud.perrin6@gmail.com>
Project-URL: Homepage, https://github.com/thibaud-perrin/proj2md
Project-URL: Documentation, https://github.com/thibaud-perrin/proj2md
Project-URL: Issues, https://github.com/thibaud-perrin/proj2md/issues
Keywords: llm,markdown,project structure
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: tomli>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.26.0; extra == "dev"
Requires-Dist: pytest-cov>=6.1.0; extra == "dev"
Requires-Dist: typos>=1.31.1; extra == "dev"
Requires-Dist: ruff>=0.11.2; extra == "dev"
Requires-Dist: mypy>=1.15.0; extra == "dev"
Requires-Dist: pyright>=1.1.398; extra == "dev"
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: bump2version>=1.0.1; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Dynamic: license-file

# proj2md

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/proj2md.svg)](https://pypi.org/project/proj2md)
[![Python Versions](https://img.shields.io/pypi/pyversions/proj2md.svg)](https://pypi.org/project/proj2md)

proj2md is a command-line tool that generates a comprehensive Markdown document
for any project directory. It traverses files, extracts structure and contents,
and outputs a self-descriptive `.md` file ideal for LLM ingestion or static documentation.

## Features

- Recursive directory traversal with extension filtering
- Optional ASCII tree view of the project structure
- Automatic table of contents with anchors
- YAML front-matter with project metadata (name, version, author, date)
- Modes:
  - `light`: only tree + existing README
  - `full`: complete extraction of all files
- List of dependencies from `pyproject.toml` or `poetry`
- Customizable snippet length (`--max-snippet-lines`)
- Exclusion patterns for files/folders (`--exclude`)
- Easy installation via `pip` and entry-point `proj2md`

## Installation

Requires Python 3.13 or higher.

Install from PyPI:

```bash
pip install proj2md
```

Or install locally from source:

```bash
git clone https://github.com/yourusername/proj2md.git
cd proj2md
pip install .
```

## Usage

Basic usage (note that the actual file will be prefixed with `generated_`):

Note: regardless of the name provided via `--output-file`, the output
file will be prefixed with `generated_` to avoid self-inclusion.
  
Basic usage:

```bash
proj2md --input-dir ./my_project --output-file ./project.md
```

Available options:

```bash
--input-dir, -i PATH        Root directory (default: .)
--output-file, -o FILE      Output Markdown file (default: project.md)
--with-tree / --no-tree     Include project tree (default: with-tree)
--with-deps / --no-deps     Include dependencies list (default: with-deps)
--extensions, -e EXT1,EXT2  Comma-separated extensions (default: .py,.md,.yaml,.json)
--mode [light|full]         Extraction mode (default: full)
--max-snippet-lines N       Limit lines per file snippet
--exclude, -x PAT1,PAT2     Comma-separated ignore patterns
```

## Examples

Full extraction with tree and dependencies:

```bash
proj2md -i ./src -o docs/project_full.md --with-tree --with-deps --mode full
```

Light mode (only tree + README):

```bash
proj2md -i ./src -o docs/project_light.md --no-deps --no-tree --mode light
```

## Development

A `Taskfile.yaml` is provided to simplify common development workflows.
Install the [Task runner](https://taskfile.dev/) (`task` command), then run:

```bash
# Setup development environment (venv, dependencies, pre-commit)
task setup-dev

# Run the test suite
task run-tests

# Run code formatting and linting
task linter

# Clean build artifacts and cache
task clean
```

To list all available tasks:

```bash
task --list
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing.

## Code of Conduct

This project adheres to the [Contributor Covenant](CODE_OF_CONDUCT.md).

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
