Skip to content

Commit e9cabff

Browse files
leonardosalasdleonardosalasd
committed
feat: initial release
1 parent db9ae0f commit e9cabff

12 files changed

Lines changed: 963 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
# Output
2+
*.pdf
3+
14
# Byte-compiled / optimized / DLL files
25
__pycache__/
36
*.py[codz]

‎README.md‎

Lines changed: 324 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,325 @@
1+
<div align="center">
2+
13
# doc-engine-cli
2-
A high-performance CLI to transform Markdown into professional, academic-grade LaTeX PDFs with zero configuration.
4+
5+
**Zero-config Markdown → PDF documentation engine**
6+
7+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
8+
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
9+
[![PyPI](https://img.shields.io/badge/PyPI-v0.1.0-006DAD.svg?logo=pypi&logoColor=white)](https://pypi.org/project/doc-engine-cli/)
10+
[![Typst](https://img.shields.io/badge/Powered_by-Typst-239DAD.svg?logo=typst&logoColor=white)](https://typst.app/)
11+
[![Code style: black](https://img.shields.io/badge/code_style-black-000000.svg)](https://github.com/psf/black)
12+
13+
Transform any `README.md` into a premium, print-ready PDF report — no configuration, no templates, no LaTeX.
14+
15+
```
16+
pip install doc-engine-cli
17+
```
18+
19+
---
20+
21+
</div>
22+
23+
## Overview
24+
25+
**doc-engine-cli** is a developer-first CLI tool that converts Markdown files into professionally styled PDF documents using [Typst](https://typst.app/) as its rendering backend. It is designed for teams and individual developers who need high-quality documentation artifacts without the complexity of LaTeX or manual typesetting.
26+
27+
The tool auto-detects your `README.md`, extracts metadata from Git, and produces an IEEE-inspired technical document — complete with cover page, table of contents, and premium typography — in a single command.
28+
29+
```bash
30+
doc-engine build
31+
```
32+
33+
That's it. Zero configuration required.
34+
35+
---
36+
37+
## Features
38+
39+
| Feature | Description |
40+
|---|---|
41+
| **Zero-Config** | Auto-detects `README.md`, Git author, and document title. No setup files needed. |
42+
| **Premium Typography** | Inter font family with fallback chain, justified text, and optimized line spacing. |
43+
| **Code-Centric** | Syntax-highlighted code blocks with Cascadia Code font and GitHub-style backgrounds. |
44+
| **Academic Ready** | IEEE and white paper-inspired layout with cover page and table of contents. |
45+
| **Pure Python** | No external binaries required (no Pandoc, no LaTeX). Ships as a single `pip install`. |
46+
| **Cross-Platform** | Works on Windows, macOS, and Linux with Python 3.10+. |
47+
48+
---
49+
50+
## Quick Start
51+
52+
### Installation
53+
54+
```bash
55+
pip install doc-engine-cli
56+
```
57+
58+
### Generate Your First PDF
59+
60+
Navigate to any project directory containing a `README.md` and run:
61+
62+
```bash
63+
doc-engine build
64+
```
65+
66+
The tool will:
67+
68+
1. Auto-detect `README.md` in the current directory
69+
2. Extract the document title from the first `# heading`
70+
3. Read your Git `user.name` for the author field
71+
4. Generate a `README_doc.pdf` with cover page, ToC, and formatted content
72+
73+
### Explicit Options
74+
75+
```bash
76+
doc-engine build path/to/file.md -o output.pdf -t "Custom Title" -a "Author Name"
77+
```
78+
79+
---
80+
81+
## Usage
82+
83+
### CLI Reference
84+
85+
```
86+
Usage: doc-engine build [OPTIONS] [INPUT_FILE]
87+
88+
Convert a Markdown file into a professional PDF document.
89+
90+
Arguments:
91+
INPUT_FILE Path to Markdown file (default: auto-detect README.md)
92+
93+
Options:
94+
-o, --output TEXT Output PDF file path (default: <input>_doc.pdf)
95+
-t, --title TEXT Document title override (default: first # heading)
96+
-a, --author TEXT Author name override (default: git user.name)
97+
--open Open PDF after generation
98+
--version Show version and exit
99+
--help Show this message and exit
100+
```
101+
102+
### Examples
103+
104+
**Basic — zero-config mode:**
105+
```bash
106+
cd my-project
107+
doc-engine build
108+
# → Generates README_doc.pdf
109+
```
110+
111+
**Specify input and output:**
112+
```bash
113+
doc-engine build CONTRIBUTING.md -o contributing_guide.pdf
114+
```
115+
116+
**Override metadata:**
117+
```bash
118+
doc-engine build -t "API Reference v2.0" -a "Engineering Team"
119+
```
120+
121+
**Generate and open immediately:**
122+
```bash
123+
doc-engine build --open
124+
```
125+
126+
**Use as Python module:**
127+
```bash
128+
python -m doc_engine build README.md
129+
```
130+
131+
---
132+
133+
## Architecture
134+
135+
```
136+
┌─────────────┐
137+
│ README.md │
138+
└──────┬──────┘
139+
│
140+
┌──────▼──────┐
141+
│ CLI Layer │ click + rich
142+
│ (cli.py) │ arg parsing, git detection
143+
└──────┬──────┘
144+
│
145+
┌────────────┼────────────┐
146+
│ │
147+
┌──────▼──────┐ ┌───────▼──────┐
148+
│ Converter │ │ Compiler │
149+
│(converter.py)│ │(compiler.py) │
150+
│ │ │ │
151+
│ Markdown AST │ │ Typst → PDF │
152+
│ → Typst │ │ via typst-py│
153+
└──────┬──────┘ └───────┬──────┘
154+
│ │
155+
│ ┌──────────────┐ │
156+
└────► report.typ ◄─────┘
157+
│ (template) │
158+
└──────┬──────┘
159+
│
160+
┌──────▼──────┐
161+
│ output.pdf │
162+
└─────────────┘
163+
```
164+
165+
### Pipeline
166+
167+
| Stage | Module | Responsibility |
168+
|---|---|---|
169+
| **1. Input Resolution** | `cli.py` | Locate Markdown file, detect Git metadata |
170+
| **2. Markdown Parsing** | `converter.py` | Parse Markdown AST via `mistune`, emit Typst markup |
171+
| **3. Template Injection** | `compiler.py` | Merge converted content with `report.typ` template |
172+
| **4. PDF Compilation** | `compiler.py` | Compile via `typst` Python bindings |
173+
174+
---
175+
176+
## How It Works
177+
178+
### Markdown → Typst Conversion
179+
180+
The converter module parses Markdown using [`mistune`](https://github.com/lepture/mistune) and generates equivalent Typst markup:
181+
182+
| Markdown | Typst Output |
183+
|---|---|
184+
| `# Heading` | `= Heading` |
185+
| `**bold**` | `*bold*` |
186+
| `*italic*` | `_italic_` |
187+
| `` `code` `` | `` `code` `` |
188+
| `[text](url)` | `#link("url")[text]` |
189+
| `- item` | `- item` |
190+
| `1. item` | `+ item` |
191+
| `> blockquote` | `#block(...)` |
192+
| `---` | `#line(...)` |
193+
194+
Special characters (`#`, `$`, `@`, `*`, `_`, etc.) are automatically escaped to prevent Typst interpretation.
195+
196+
### PDF Template
197+
198+
The included `report.typ` template provides:
199+
200+
- **Cover page** with title, author, and date
201+
- **Table of contents** with depth-3 navigation
202+
- **Running headers** with document title and author
203+
- **Page footer** with page numbers and engine attribution
204+
- **Code blocks** with rounded corners and subtle borders
205+
- **Heading hierarchy** with accent-colored H2 sections
206+
207+
---
208+
209+
## Project Structure
210+
211+
```
212+
doc-engine-cli/
213+
├── doc_engine/
214+
│ ├── __init__.py # Package version
215+
│ ├── __main__.py # python -m doc_engine entrypoint
216+
│ ├── cli.py # Click-based CLI + Git detection
217+
│ ├── converter.py # Markdown → Typst transpiler
218+
│ ├── compiler.py # Typst → PDF compilation engine
219+
│ └── templates/
220+
│ └── report.typ # Professional Typst report template
221+
├── tests/
222+
│ ├── __init__.py
223+
│ └── test_converter.py # Unit tests for converter module
224+
├── pyproject.toml # Package configuration + dependencies
225+
├── LICENSE # MIT License
226+
├── .gitignore
227+
└── README.md
228+
```
229+
230+
---
231+
232+
## Dependencies
233+
234+
| Package | Purpose | License |
235+
|---|---|---|
236+
| [`click`](https://click.palletsprojects.com/) | CLI framework | BSD-3 |
237+
| [`rich`](https://github.com/Textualize/rich) | Terminal formatting and progress indicators | MIT |
238+
| [`mistune`](https://github.com/lepture/mistune) | Markdown parser (pure Python) | BSD-3 |
239+
| [`typst`](https://github.com/messense/typst-py) | Typst compiler bindings | Apache-2.0 |
240+
241+
All dependencies are pure Python — no external binaries (Pandoc, LaTeX, etc.) are required.
242+
243+
---
244+
245+
## Development
246+
247+
### Setup
248+
249+
```bash
250+
git clone https://github.com/leonardosalasd/doc-engine-cli.git
251+
cd doc-engine-cli
252+
pip install -e ".[dev]"
253+
```
254+
255+
### Run Tests
256+
257+
```bash
258+
python -m pytest tests/ -v
259+
```
260+
261+
### Project Commands
262+
263+
```bash
264+
# Generate PDF from this project's README
265+
python -m doc_engine build
266+
267+
# Run with verbose error output
268+
python -m doc_engine build README.md -o docs_output.pdf
269+
```
270+
271+
---
272+
273+
## Supported Markdown Elements
274+
275+
- [x] Headings (H1–H6)
276+
- [x] Bold, italic, strikethrough
277+
- [x] Inline code and fenced code blocks (with language hints)
278+
- [x] Links
279+
- [x] Ordered and unordered lists
280+
- [x] Nested lists
281+
- [x] Blockquotes
282+
- [x] Tables
283+
- [x] Horizontal rules
284+
- [x] Line breaks (`<br>`)
285+
- [ ] Images (rendered as alt-text; remote images not embedded)
286+
- [ ] Footnotes
287+
- [ ] Math blocks
288+
289+
---
290+
291+
## Roadmap
292+
293+
- [ ] Custom template injection via `--template` flag
294+
- [ ] Multi-file documentation merge
295+
- [ ] GitHub Actions integration for CI/CD pipelines
296+
- [ ] Dark-mode PDF theme variant
297+
- [ ] Image downloading and embedding for remote URLs
298+
- [ ] YAML front-matter support for metadata override
299+
- [ ] PDF/A compliance for archival
300+
301+
---
302+
303+
## Contributing
304+
305+
Contributions are welcome. Please follow these guidelines:
306+
307+
1. Fork the repository
308+
2. Create a feature branch (`git checkout -b feature/your-feature`)
309+
3. Write tests for new functionality
310+
4. Ensure all tests pass (`python -m pytest tests/ -v`)
311+
5. Submit a pull request
312+
313+
---
314+
315+
## License
316+
317+
This project is licensed under the [MIT License](LICENSE).
318+
319+
---
320+
321+
<div align="center">
322+
323+
**Built with [Typst](https://typst.app/) · Parsed with [mistune](https://github.com/lepture/mistune) · Styled with [Rich](https://github.com/Textualize/rich)**
324+
325+
</div>

‎doc_engine/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
__version__ = "0.1.0"

‎doc_engine/__main__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
from doc_engine.cli import main
2+
3+
main()

0 commit comments

Comments
 (0)