chaptr 0.1.1__tar.gz

chaptr-0.1.1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: chaptr
+Version: 0.1.1
+Summary: Build independent Markdown document projects with shared variables and CSS themes.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: markdown-it-py<5,>=3
+Requires-Dist: mdit-py-plugins<1,>=0.5
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: pdf
+Requires-Dist: WeasyPrint<70,>=68; extra == "pdf"
+Requires-Dist: pypdf<7,>=6; extra == "pdf"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pypdf<7,>=6; extra == "dev"
+
+# chaptr
+
+Turn separate Markdown chapters into one document, with shared variables and
+editable themes. Produce merged Markdown, styled HTML or PDF.
+
+## Usage
+
+chaptr runs in your terminal. Install it once and use it across document projects.
+See [installation instructions](docs/01-requirements.md#installation) for the
+source checkout and GitHub release wheel options.
+
+| Command | Purpose |
+| --- | --- |
+| `chaptr init [directory]` | Create an editable copy of the app's documentation |
+| `chaptr build` | Build the current project; HTML is the default |
+| `chaptr build --format pdf` | Generate PDF when renderer dependencies are available |
+| `chaptr help` | Read the bundled command manual |
+| `chaptr --help` | List commands; each command also supports `--help` |
+
+See the [documentation](docs/README.md) for requirements, the user workflow,
+configuration, themes and current limitations. The documentation is itself an
+chaptr project, so you can try the tool on its own source:
+
+```sh
+chaptr build --config docs/document.yaml
+```
+
+## Changelog
+
+### 0.1.1 - Unreleased
+
+- Renamed the package and command to chaptr.
+- Added publishing to PyPI through GitHub Actions Trusted Publishing.
+
+### 0.1.0
+
+- Project initialization with the app's documentation and overwrite protection.
+- Ordered Markdown chapters and simple shared variables.
+- Automatic table captions, linked footnotes and a table of contents.
+- Optional title pages, covers and author sections.
+- Pre-designed PDF covers with page-size validation and preserved contents links.
+- Markdown and HTML output, with an optional WeasyPrint PDF renderer.
+- Bundled themes, project-local overrides and additional stylesheets.
+- Command help and a bundled usage manual.
+
+PDF requires native libraries.
+
+Planned: [named document templates](docs/07-roadmap.md), including roleplaying
+scenarios and workplace accessibility documents. Template selection is not available yet.

chaptr-0.1.1/README.md

@@ -0,0 +1,49 @@
+# chaptr
+
+Turn separate Markdown chapters into one document, with shared variables and
+editable themes. Produce merged Markdown, styled HTML or PDF.
+
+## Usage
+
+chaptr runs in your terminal. Install it once and use it across document projects.
+See [installation instructions](docs/01-requirements.md#installation) for the
+source checkout and GitHub release wheel options.
+
+| Command | Purpose |
+| --- | --- |
+| `chaptr init [directory]` | Create an editable copy of the app's documentation |
+| `chaptr build` | Build the current project; HTML is the default |
+| `chaptr build --format pdf` | Generate PDF when renderer dependencies are available |
+| `chaptr help` | Read the bundled command manual |
+| `chaptr --help` | List commands; each command also supports `--help` |
+
+See the [documentation](docs/README.md) for requirements, the user workflow,
+configuration, themes and current limitations. The documentation is itself an
+chaptr project, so you can try the tool on its own source:
+
+```sh
+chaptr build --config docs/document.yaml
+```
+
+## Changelog
+
+### 0.1.1 - Unreleased
+
+- Renamed the package and command to chaptr.
+- Added publishing to PyPI through GitHub Actions Trusted Publishing.
+
+### 0.1.0
+
+- Project initialization with the app's documentation and overwrite protection.
+- Ordered Markdown chapters and simple shared variables.
+- Automatic table captions, linked footnotes and a table of contents.
+- Optional title pages, covers and author sections.
+- Pre-designed PDF covers with page-size validation and preserved contents links.
+- Markdown and HTML output, with an optional WeasyPrint PDF renderer.
+- Bundled themes, project-local overrides and additional stylesheets.
+- Command help and a bundled usage manual.
+
+PDF requires native libraries.
+
+Planned: [named document templates](docs/07-roadmap.md), including roleplaying
+scenarios and workplace accessibility documents. Template selection is not available yet.

chaptr-0.1.1/chaptr.egg-info/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: chaptr
+Version: 0.1.1
+Summary: Build independent Markdown document projects with shared variables and CSS themes.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: markdown-it-py<5,>=3
+Requires-Dist: mdit-py-plugins<1,>=0.5
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: pdf
+Requires-Dist: WeasyPrint<70,>=68; extra == "pdf"
+Requires-Dist: pypdf<7,>=6; extra == "pdf"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pypdf<7,>=6; extra == "dev"
+
+# chaptr
+
+Turn separate Markdown chapters into one document, with shared variables and
+editable themes. Produce merged Markdown, styled HTML or PDF.
+
+## Usage
+
+chaptr runs in your terminal. Install it once and use it across document projects.
+See [installation instructions](docs/01-requirements.md#installation) for the
+source checkout and GitHub release wheel options.
+
+| Command | Purpose |
+| --- | --- |
+| `chaptr init [directory]` | Create an editable copy of the app's documentation |
+| `chaptr build` | Build the current project; HTML is the default |
+| `chaptr build --format pdf` | Generate PDF when renderer dependencies are available |
+| `chaptr help` | Read the bundled command manual |
+| `chaptr --help` | List commands; each command also supports `--help` |
+
+See the [documentation](docs/README.md) for requirements, the user workflow,
+configuration, themes and current limitations. The documentation is itself an
+chaptr project, so you can try the tool on its own source:
+
+```sh
+chaptr build --config docs/document.yaml
+```
+
+## Changelog
+
+### 0.1.1 - Unreleased
+
+- Renamed the package and command to chaptr.
+- Added publishing to PyPI through GitHub Actions Trusted Publishing.
+
+### 0.1.0
+
+- Project initialization with the app's documentation and overwrite protection.
+- Ordered Markdown chapters and simple shared variables.
+- Automatic table captions, linked footnotes and a table of contents.
+- Optional title pages, covers and author sections.
+- Pre-designed PDF covers with page-size validation and preserved contents links.
+- Markdown and HTML output, with an optional WeasyPrint PDF renderer.
+- Bundled themes, project-local overrides and additional stylesheets.
+- Command help and a bundled usage manual.
+
+PDF requires native libraries.
+
+Planned: [named document templates](docs/07-roadmap.md), including roleplaying
+scenarios and workplace accessibility documents. Template selection is not available yet.

chaptr-0.1.1/chaptr.egg-info/SOURCES.txt

@@ -0,0 +1,31 @@
+README.md
+pyproject.toml
+chaptr.egg-info/PKG-INFO
+chaptr.egg-info/SOURCES.txt
+chaptr.egg-info/dependency_links.txt
+chaptr.egg-info/entry_points.txt
+chaptr.egg-info/requires.txt
+chaptr.egg-info/top_level.txt
+docs/00-authors.md
+docs/00-front-cover.md
+docs/01-requirements.md
+docs/02-workflow.md
+docs/03-configuration.md
+docs/04-themes.md
+docs/05-pdf.md
+docs/06-limitations.md
+docs/07-roadmap.md
+docs/99-back-cover.md
+docs/README.md
+docs/document.yaml
+docs/styles.css
+src/chaptr/__init__.py
+src/chaptr/cli.py
+src/chaptr/manual.txt
+src/chaptr/pdf.py
+src/chaptr/render.py
+src/chaptr/themes/base.css
+src/chaptr/themes/modern.css
+src/chaptr/themes/vintage.css
+tests/test_build.py
+tests/test_pdf.py

chaptr-0.1.1/chaptr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chaptr-0.1.1/chaptr.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chaptr = chaptr.cli:main

chaptr-0.1.1/chaptr.egg-info/requires.txt

@@ -0,0 +1,11 @@
+markdown-it-py<5,>=3
+mdit-py-plugins<1,>=0.5
+PyYAML<7,>=6
+
+[dev]
+pytest<10,>=8
+pypdf<7,>=6
+
+[pdf]
+WeasyPrint<70,>=68
+pypdf<7,>=6

chaptr-0.1.1/chaptr.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+chaptr
+chaptr_docs

chaptr-0.1.1/docs/00-authors.md

@@ -0,0 +1,5 @@
+# Authors
+
+$app_name is maintained by its contributors.
+
+This document describes version $app_version.

chaptr-0.1.1/docs/00-front-cover.md

@@ -0,0 +1,5 @@
+# $app_name
+
+Documentation
+
+Version $app_version

chaptr-0.1.1/docs/01-requirements.md

@@ -0,0 +1,71 @@
+# Requirements
+
+## Runtime
+
+- Python 3.11 or newer.
+- The chaptr package, installed in a Python environment accessible from your terminal.
+- `markdown-it-py`, `mdit-py-plugins` and `PyYAML`, installed automatically with chaptr.
+- Windows, macOS or Linux. Document source files use UTF-8.
+
+The installed command must be available on `PATH` or called by its full path.
+If installed in a virtual environment, activate it or call its executable directly.
+One installation can serve multiple document projects.
+
+## Installation
+
+To install from PyPI, or upgrade an existing installation, run:
+
+```sh
+python -m pip install --upgrade chaptr
+```
+
+To install a wheel from a GitHub release, download `chaptr-0.1.1-py3-none-any.whl`
+and run this command from the directory containing the downloaded file:
+
+```sh
+python -m pip install ./chaptr-0.1.1-py3-none-any.whl
+```
+
+To install from a source checkout, run this from the repository root:
+
+```sh
+python -m pip install .
+```
+
+To build a wheel from the source checkout, install the build tool and run:
+
+```sh
+python -m pip install build
+python -m build --wheel
+```
+
+The wheel is written to `dist/` and can be attached to a GitHub release.
+
+## PyPI Publishing
+
+The `.github/workflows/publish.yml` workflow builds and publishes the package
+when a GitHub Release is published. Configure a Trusted Publisher for project
+`chaptr` on PyPI with the repository owner and name, workflow filename
+`publish.yml` and environment `pypi`. Create the `pypi` environment under the
+GitHub repository's Settings > Environments. The current repository is
+`clkjunk/mdoc`; update the PyPI publisher if you rename it.
+
+A pending publisher does not reserve the `chaptr` name. The first successful
+upload creates the PyPI project, so publish when the release is ready.
+
+## PDF Dependencies
+
+PDF additionally requires WeasyPrint and native libraries, including Pango.
+PDF cover assembly uses pypdf, included in the `pdf` extra.
+HTML, Markdown, initialization and help do not require those components.
+Platform-specific requirements are described in the PDF Rendering section.
+
+## Development
+
+- `setuptools` is the package build backend.
+- The `dev` extra supplies `pytest` and `pypdf` for the test suite.
+- Development uses an editable installation: `python -m pip install -e ".[dev]"`.
+- Run tests with `python -m pytest -q`.
+- The `pdf` extra supplies WeasyPrint and pypdf but does not install native libraries.
+
+A standalone executable and installer are not available; install chaptr with pip.

chaptr-0.1.1/docs/02-workflow.md

@@ -0,0 +1,69 @@
+# User Workflow
+
+Use $app_name $app_version to create a document, edit its source files and rebuild
+whenever the content changes.
+
+## Create a Project
+
+```sh
+chaptr init my-document
+cd my-document
+```
+
+Or run `chaptr init` inside the directory you want to use. Initialization is
+noninteractive. Its default content is $app_name's own documentation: the section
+files, `README.md`, `document.yaml` and `styles.css`, plus a `.gitignore` that
+excludes generated build output. The files come bundled with the CLI.
+
+Open `README.md` to read the documentation or run `chaptr build` to render it.
+Replace the sections with your own content when ready.
+
+Existing starter files are never overwritten. Conflicts stop initialization
+before files are written; unrelated files are kept. There is no force option.
+
+## Edit the Content
+
+1. Set shared values in the configuration's `variables` mapping.
+2. Edit the Markdown chapters with any text editor.
+3. Add new chapter paths to `files` in the order they should appear.
+4. Select a theme or adjust the project stylesheet when needed.
+
+Rename or replace the documentation sections and update `files` accordingly.
+Named project templates are future work; `init` currently has one default only.
+
+## Build
+
+```sh
+chaptr build
+chaptr build --format markdown
+chaptr build --format pdf
+```
+
+The default format is HTML. PDF needs the additional renderer dependencies.
+The output directory is created on the first build and receives `document.html`,
+`document.md` or `document.pdf`. Rebuilding a format replaces its previous file;
+other formats are untouched. Successful builds print the output path.
+
+Open HTML directly in a browser.
+
+## Work from Another Directory
+
+```sh
+chaptr build --config "path/to/my-document/document.yaml"
+```
+
+Without `--config`, chaptr uses `document.yaml` in the current directory.
+All configured paths are resolved relative to that YAML file. Quote paths
+containing spaces.
+
+## Get Help
+
+```sh
+chaptr --help
+chaptr init --help
+chaptr build --help
+chaptr help
+```
+
+Exit codes are `0` for success, `1` for initialization or build errors and `2`
+for invalid command-line usage. Help works without a document project.

chaptr-0.1.1/docs/03-configuration.md

@@ -0,0 +1,133 @@
+# Configuration and Variables
+
+Each document project has a YAML configuration. Only `files` is required.[^paths]
+
+```yaml
+title: Product Guide
+theme: modern
+stylesheet: styles.css
+output: build
+files:
+  - chapters/01-introduction.md
+  - chapters/02-requirements.md
+variables:
+  product_name: Field Notes
+  version: "1.0"
+```
+
+## Fields
+
+Table: Configuration fields
+
+| Field | Meaning | Default |
+| --- | --- | --- |
+| `files` | Nonempty list of Markdown paths, in chapter order | Required |
+| `title` | HTML document title | Document |
+| `theme` | Named CSS theme for HTML and PDF | modern |
+| `stylesheet` | Extra project CSS applied after the theme | None |
+| `output` | Directory for generated files | build |
+| `variables` | Shared text, numeric or boolean values | Empty mapping |
+| `title_page` | Generate a title page using title, subtitle and author | false |
+| `subtitle` | Subtitle on the generated title page | Empty |
+| `author` | Author text on the generated title page | Empty |
+| `front_cover` | Markdown or single-page PDF front cover | None |
+| `author_section` | Markdown file for author details | None |
+| `table_of_contents` | Generate linked contents with PDF page numbers | false |
+| `toc_depth` | Heading levels included in contents, from 1 to 6 | 2 |
+| `back_cover` | Markdown or single-page PDF back cover | None |
+
+Configured paths are relative to the configuration file. To use a different
+configuration filename, pass its path with `--config`.
+
+## Variables
+
+Reference a shared value using `$product_name`:
+
+```markdown
+# $product_name
+
+Product guide, version $version.
+```
+
+Names contain letters, digits or underscores and cannot begin with a digit.
+Undefined names stop the build with a source filename and line number.
+Values are inserted as Markdown, so they may affect the rendered formatting.
+
+Write `$$` for a literal dollar sign: `$$20` becomes `$20` in ordinary text.
+Code blocks and ordinary inline code retain their original contents.
+Multiline inline code is a current exception.
+
+Only variable substitution is supported.
+
+## Table Captions
+
+Place a standalone `Table: Caption text` paragraph directly above or below a table:
+
+```markdown
+Table: Release formats
+
+| Format | Extension |
+| --- | --- |
+| HTML | .html |
+| PDF | .pdf |
+```
+
+Captions become `Table 1. Release formats`, numbered across the document in chapter
+order. Moving or inserting captioned tables updates their numbers. Tables without
+captions stay unnumbered. Use one caption per table. Caption text supports inline
+Markdown. A caption below the source table is displayed below it.
+
+## Footnotes
+
+Use Markdown footnote references and definitions:
+
+```markdown
+An explanation with a note.[^detail]
+
+[^detail]: Additional information with **formatting**.
+```
+
+Notes are numbered by first reference across the document and collected in a
+linked Notes section before the back cover. References and definitions can be in
+different chapters; use unique labels throughout the project. Notes currently
+appear at the end of the document, not at the bottom of individual PDF pages.
+
+## Document Pages
+
+```yaml
+title: Product Guide
+subtitle: Release documentation
+author: Example Author
+title_page: true
+front_cover: front-cover.md
+author_section: authors.md
+table_of_contents: true
+toc_depth: 2
+back_cover: back-cover.md
+```
+
+All these options are optional. Page order is front cover, title page, author
+section, contents, chapters, notes and back cover. Markdown covers and author files
+support variables and images. Do not list them again in `files`. The title,
+subtitle and author fields are plain text.
+
+For externally designed covers:
+
+```yaml
+front_cover: covers/front.pdf
+back_cover: covers/back.pdf
+```
+
+PDF covers must be unencrypted single-page files matching the generated page size.
+They are attached unchanged to the final PDF. HTML and Markdown builds omit them.
+See [PDF Rendering](05-pdf.md) for validation and page-numbering details.
+
+Contents include chapter headings up to `toc_depth`. Duplicate heading names get
+unique IDs such as `requirements` and `requirements-2`. HTML contents use links;
+PDF contents also show page numbers.
+
+HTML and PDF generate title pages, contents and numbered captions. Merged Markdown
+includes Markdown cover and author sections and preserves caption and footnote
+syntax. It does not generate title-page or contents markup.
+
+[^paths]: Source and output paths are resolved relative to the configuration file.

chaptr-0.1.1/docs/04-themes.md

@@ -0,0 +1,94 @@
+# Themes
+
+Themes are editable CSS. The application bundles `modern` and `vintage`; document
+projects can replace either theme or define a new name without modifying the app.
+
+## Choose a Theme
+
+Set `theme: vintage` in the configuration or override it for one build:
+
+```sh
+chaptr build --theme vintage
+```
+
+Theme selection applies to HTML and PDF.
+
+## Customize
+
+For small adjustments, create a project stylesheet and configure
+`stylesheet: styles.css`:
+
+```css
+body { font-family: Georgia, serif; line-height: 1.75; }
+th { background: #edf4f0; }
+@page { size: A4; margin: 25mm; }
+```
+
+For a complete theme, create `themes/company.css` and configure `theme: company`.
+A local `themes/modern.css` replaces the bundled modern theme only for that
+project. Default themes remain part of the installed application.
+
+Styling is applied in this order:
+
+1. Shared application base CSS.
+2. The project-local named theme or the bundled theme if no local replacement exists.
+3. The optional configured stylesheet.
+
+## Print Styling
+
+The base print layout uses A4 pages, 20mm margins and a page break between chapters.
+Use `@page` to adjust page size and margins and `@media print` for print-only rules.
+Fonts must be available on the rendering machine or supplied as local font assets.
+
+HTML and PDF share CSS, but browser and WeasyPrint support differ. Keep print CSS
+conservative and verify the actual PDF. Relative CSS asset URLs currently resolve
+from the document project's root.
+
+## Document Elements
+
+Use `caption` to style table labels. Their top or bottom placement follows the
+caption's source position. `.front-cover`, `.title-page`, `.author-section`,
+`.contents` and `.back-cover` style the optional document pages.
+
+```css
+caption { color: #24634b; font-size: 10pt; }
+.title-page { text-align: center; }
+.footnotes { font-size: 9pt; }
+```
+
+The base print theme starts each optional page separately. Contents page numbers
+use WeasyPrint's `target-counter` support. Custom themes can override these rules.
+External PDF covers keep their own styling; theme rules apply to generated pages.
+
+## Editable Stat Blocks
+
+Wrap ordinary Markdown in `::: monster` and a closing `:::` to render a
+single-column stat block. Use an H2 for its name, an italic paragraph for its
+description, a table for attributes and H3 headings for any ability sections.
+Section names and statistics are not tied to a particular game system.
+
+```markdown
+::: monster
+## Example Creature
+*Medium humanoid*
+
+**AC:** 12  
+**HP:** 40
+
+| STR | DEX | CON |
+| --- | --- | --- |
+| 9 (-1) | 14 (+2) | 11 (+0) |
+
+### Actions
+**Strike.** Write the complete action here.
+:::
+```
+
+Include only the sections needed, such as actions, spells or reactions. Leave a
+blank line between paragraphs; two trailing spaces create a line break within
+a paragraph. The block's headings receive link targets but do not enter the
+document table of contents. Keep the closing delimiter in the same chapter.
+
+Style `.monster-card` in the project stylesheet. Override `--monster-accent`
+and `--monster-rule` on that selector to change its colors. HTML and PDF render
+the block; Markdown output preserves the source syntax. Raw HTML remains disabled.

chaptr-0.1.1/docs/05-pdf.md

@@ -0,0 +1,70 @@
+# PDF Rendering
+
+chaptr renders the configured Markdown to HTML, applies CSS and passes that document
+to WeasyPrint for PDF generation.
+
+```sh
+chaptr build --format pdf
+```
+
+## Requirements
+
+The optional `pdf` extra supplies WeasyPrint and pypdf. For development in the application
+repository, install it with `python -m pip install -e ".[pdf]"`.
+For a wheel installation, request its extra:
+
+```sh
+python -m pip install "path/to/chaptr-0.1.1-py3-none-any.whl[pdf]"
+```
+
+WeasyPrint also needs native system libraries, including Pango. These are compiled
+components for font handling and text layout.
+Installing the Python extra alone may not be sufficient.
+
+Follow the current [WeasyPrint platform requirements](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation)
+for Windows, macOS or Linux.
+
+## PDF Covers
+
+Export a single-page PDF for each cover from your design tool, then configure:
+
+```yaml
+front_cover: covers/front.pdf
+back_cover: covers/back.pdf
+```
+
+Either cover is optional. Paths are relative to the project configuration.
+Build with `chaptr build --format pdf` to combine the front cover, generated content
+and back cover into one PDF. A cover can also be Markdown; mixed types work.
+
+PDF covers retain their artwork, fonts and page content. Generated content margins
+and theme CSS do not add borders to them. Export the design to the page edges for
+an edge-to-edge cover. Covers are not scaled or cropped during assembly.
+
+Each PDF cover must be unencrypted and contain exactly one page. Its page size
+must match the adjacent generated page, allowing a rounding difference of one
+PDF point. An A4 document needs A4 covers; a landscape cover needs matching
+document orientation. Invalid covers fail the build before existing output is
+replaced. Source cover files cannot also be the output document.
+
+The final PDF keeps the generated document's title metadata, bookmarks and linked
+destinations. An inserted front cover counts as page 1, so contents page numbers
+match the final PDF's physical pages. Avoid overriding the PDF page counter in
+custom themes when using this numbering scheme.
+
+HTML and Markdown builds omit PDF covers. They can still be used to preview and
+edit the content. The docs project keeps Markdown covers as its editable default.
+Print-production bleed and trim configuration are not provided.
+
+## Current Status
+
+PDF generation has been checked on the Windows development setup, including
+document pages, captions, notes, PDF covers and contents page numbers. A clean-machine
+installation has not yet been verified.
+
+Missing renderer dependencies produce a build error. HTML and Markdown output,
+initialization and help remain available without them.
+
+Self-contained releases are planned to bundle Python, WeasyPrint and native
+libraries so users do not need separate setup. Those bundles are not implemented
+or verified yet. The current wheel requires Python.