readwright 0.3.0__py3-none-any.whl

readwright/templates/base.md.j2

@@ -0,0 +1,21 @@
+{% block header %}{% include "partials/header.md.j2" %}{% endblock %}
+
+{% block badges %}{% include "partials/badges.md.j2" %}{% block badges_extra %}{% endblock +%}
+{% endblock %}
+
+{% block donate %}{% include "partials/donate.md.j2" %}{% block donate_extra %}{% endblock +%}
+{% endblock %}
+
+{% block toc %}{% endblock %}
+
+{% block screenshots %}{% include "partials/screenshots.md.j2" %}{% endblock %}
+
+{% block install %}{% include "partials/install.md.j2" %}{% endblock %}
+
+{% block usage %}{% include "partials/usage.md.j2" %}{% endblock %}
+
+{% block extra %}{% endblock %}
+
+{% block contributing %}{% include "partials/contributing.md.j2" %}{% endblock %}
+
+{% block license %}{% include "partials/license.md.j2" %}{% endblock %}

readwright/templates/partials/badges.md.j2

@@ -0,0 +1 @@
+{{ badges() -}}

readwright/templates/partials/contributing.md.j2

@@ -0,0 +1,7 @@
+## Contributing
+
+{% if project.url %}
+Issues and pull requests are welcome at [{{ project.owner }}/{{ project.repo }}]({{ project.url }}).
+{% else %}
+Issues and pull requests are welcome.
+{% endif %}

readwright/templates/partials/donate.md.j2

@@ -0,0 +1 @@
+{{ donate_badges() -}}

readwright/templates/partials/header.md.j2

@@ -0,0 +1,10 @@
+{% set hero = banner() %}
+{% if hero %}
+{{ hero }}
+
+{% endif %}
+# {{ project.name }}
+
+{% if project.tagline %}
+{{ project.tagline }}
+{% endif %}

readwright/templates/partials/install.md.j2

@@ -0,0 +1,46 @@
+## Installation
+
+{% if project.project_type == "python" and project.pypi %}
+```sh
+pip install {{ project.pypi }}
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install {{ project.pypi }}
+```
+{% elif project.project_type == "node" and project.npm %}
+```sh
+npm install {{ project.npm }}
+```
+{% elif project.project_type == "rust" and project.crate %}
+```sh
+cargo install {{ project.crate }}
+```
+{% elif project.project_type == "go" and project.go_module %}
+```sh
+go install {{ project.go_module }}@latest
+```
+{% elif project.project_type == "dotnet" and project.nuget %}
+```sh
+dotnet tool install --global {{ project.nuget }}
+```
+{% elif project.project_type == "minecraft-mod" %}
+Download the latest release from the [releases page]({{ project.url ~ "/releases/latest" if project.url else "#" }})
+and drop the jar into your `mods` folder{% if project.minecraft_version %} (Minecraft {{ project.minecraft_version }}){% endif %}.
+{% elif project.project_type == "flow-plugin" %}
+In [Flow Launcher](https://www.flowlauncher.com/), type:
+
+{{ flow_install_cmd() }}
+{% elif project.project_type == "hacs" %}
+Install through [HACS](https://hacs.xyz/){% if project.url %} by adding `{{ project.owner }}/{{ project.repo }}` as a custom repository{% endif %},
+then add the resource to your dashboard.
+{% elif project.url %}
+```sh
+git clone {{ project.url }}.git
+cd {{ project.repo }}
+```
+{% else %}
+Clone the repository and follow the instructions in the source tree.
+{% endif %}

readwright/templates/partials/license.md.j2

@@ -0,0 +1,5 @@
+{% if project.license %}
+## License
+
+{{ project.license }}
+{% endif %}

readwright/templates/partials/screenshots.md.j2

@@ -0,0 +1,5 @@
+{% if has_screenshots() %}
+## Screenshots
+
+{{ screenshots() }}
+{% endif %}

readwright/templates/partials/usage.md.j2

@@ -0,0 +1,5 @@
+{% if vars.usage is defined %}
+## Usage
+
+{{ vars.usage }}
+{% endif %}

readwright/toc.py

@@ -0,0 +1,60 @@
+"""Table-of-contents generation from rendered markdown headings."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+
+TOC_PREFIX = "<!-- readwright:toc"
+TOC_TOKEN = f"{TOC_PREFIX} -->"
+TOC_ANY = re.compile(r"<!-- readwright:toc(?: (?P<min>\d) (?P<max>\d))? -->")
+HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$")
+FENCE = re.compile(r"^\s*(```|~~~)")
+SLUG_STRIP = re.compile(r"[^\w\- ]", re.UNICODE)
+
+
+def toc_token(min_level: int = 2, max_level: int = 3) -> str:
+    return f"{TOC_PREFIX} {min_level} {max_level} -->"
+
+
+def github_slug(title: str) -> str:
+    cleaned = SLUG_STRIP.sub("", title.strip().lower())
+    return cleaned.replace(" ", "-")
+
+
+def _headings(markdown: str) -> list[tuple[int, str]]:
+    found: list[tuple[int, str]] = []
+    in_fence = False
+    for line in markdown.splitlines():
+        if FENCE.match(line):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        if match := HEADING.match(line):
+            found.append((len(match.group(1)), match.group(2).strip()))
+    return found
+
+
+def build_toc(markdown: str, min_level: int = 2, max_level: int = 3) -> str:
+    seen: Counter[str] = Counter()
+    lines = []
+    for level, title in _headings(markdown):
+        if not min_level <= level <= max_level:
+            continue
+        slug = github_slug(title)
+        count = seen[slug]
+        seen[slug] += 1
+        anchor = f"{slug}-{count}" if count else slug
+        lines.append(f"{'  ' * (level - min_level)}- [{title}](#{anchor})")
+    return "\n".join(lines)
+
+
+def insert_toc(markdown: str) -> str:
+    match = TOC_ANY.search(markdown)
+    if not match:
+        return markdown
+    min_level = int(match["min"]) if match["min"] else 2
+    max_level = int(match["max"]) if match["max"] else 3
+    before, after = markdown[: match.start()], markdown[match.end() :]
+    return before + build_toc(after, min_level, max_level) + after

readwright-0.3.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: readwright
+Version: 0.3.0
+Summary: Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers
+Project-URL: Homepage, https://github.com/Garulf/readwright
+Project-URL: Issues, https://github.com/Garulf/readwright/issues
+Author-email: Garulf <535299+Garulf@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: badges,jinja2,markdown,readme,shields
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer>=0.12
+Requires-Dist: watchfiles>=1.2.0
+Description-Content-Type: text/markdown
+
+<!-- generated by readwright from README.md.j2; edit the template, not this file -->
+# readwright
+
+Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers.
+
+[![PyPI](https://img.shields.io/pypi/v/readwright)](https://pypi.org/project/readwright/) [![Python](https://img.shields.io/pypi/pyversions/readwright)](https://pypi.org/project/readwright/) [![License](https://img.shields.io/github/license/Garulf/readwright)](https://github.com/Garulf/readwright/blob/main/LICENSE) [![CI](https://img.shields.io/github/actions/workflow/status/Garulf/readwright/ci.yml)](https://github.com/Garulf/readwright/actions/workflows/ci.yml) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Template helpers](#template-helpers)
+- [Configuration](#configuration)
+- [pre-commit and GitHub Actions](#pre-commit-and-github-actions)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+```sh
+pip install readwright
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install readwright
+```
+
+## Quick start
+
+```sh
+cd my-repo
+readwright init      # writes readme.yaml + README.md.j2 (autodetects owner/repo, name, license, ...)
+readwright render    # writes README.md (--watch to re-render on change, -o - for stdout)
+readwright check     # exit 1 with a diff if README.md is stale (use as a pre-commit hook / in CI)
+readwright badges    # list badge presets
+readwright blocks    # list overridable blocks and partials
+readwright show partials/install.md.j2   # print a packaged template to copy and tweak
+```
+
+Already have a README? `readwright init --from-readme` moves its body into the template so nothing is
+lost, then takes over `README.md`. Prefer `pyproject.toml`? `readwright init --pyproject` writes the config
+to `[tool.readme]`.
+
+`README.md.j2` extends the packaged `base.md.j2` and overrides only what it needs:
+
+```jinja
+{% extends "base.md.j2" %}
+
+{% block usage %}
+## Usage
+
+{{ screenshot("main", width=600) }}
+
+Run `{{ project.name }} --help`.
+{% endblock %}
+```
+
+See [`examples/`](https://github.com/Garulf/readwright/tree/main/examples) for a kitchen-sink project using every helper,
+plus Minecraft mod, HACS card and Flow Launcher plugin examples.
+
+## Template helpers
+
+| Helper | Result |
+| --- | --- |
+| `badge("pypi")`, `badge("ci", workflow="test.yml")` | Preset badge built from repo metadata |
+| `shield("Discord", "chat", "5865F2", link=...)` | Custom shields.io static badge |
+| `badges()` / `donate_badges()` | All badges from `badges:` / `donate:` in config |
+| `screenshot("main", alt=..., width=...)` | Finds `docs/screenshots/main.{png,jpg,gif,webp,svg}`; `main-dark.*` + `main-light.*` become a theme-aware pair |
+| `screenshots(columns=2)` | Gallery table of every image in the screenshots dir |
+| `image("path/or/url", "alt", width=...)` | Explicit image, no discovery |
+| `screenshots(order=[...], captions={...}, subdir=...)` | Control gallery order/captions (or drop a `captions.yaml` in the folder) |
+| `toc()`, `toc(1, 2)` | Table of contents from the headings below it (min/max level) |
+| `changelog(n=1)` | Newest `n` entries of `CHANGELOG.md` |
+| `project.*`, `vars.*` | Repo metadata and free-form config values |
+| `cli_help("mytool --help")` | Runs the command and fences its output (needs `allow_exec: true`) |
+| `include_file(path)`, `code_block(path)`, `snippet(path, start, end)` | Pull a file, a fenced file, or a marked region into the README |
+| `config_table(path, section=...)`, `env_table(".env.example")`, `entry_points_table()` | Markdown tables from YAML/TOML/JSON, env files, `[project.scripts]` |
+| `gh_link("issues", "Issues")`, `spdx_link()`, `my_ha_link("hacs_repository", owner=..., repository=...)` | Repo-relative GitHub links, SPDX license link, My Home Assistant buttons |
+| `callout("tip", text)`, `details(summary, body)`, `center(html)`, `columns([...])` | GitHub alerts, collapsibles, centered blocks, side-by-side cells |
+| `logo(width=120)`, `video("demo")`, `contributors([...])` | Theme-aware logo from `docs/logo.*`, video/gif embed, avatar grid |
+| `unsplash("photo-1518…", credit="Name", user="handle", width=1000, height=280)` | Hero image from Unsplash's CDN with the required attribution line; `banner:` in config puts one above the title |
+| `flow_install_cmd()`, `mc_versions()`, `mod_dependencies()`, `related_repos()` | Flow Launcher / Minecraft mod / related-repo tables |
+| `git_sha()`, `git_tag()`, `today()` | Build metadata (these change between renders, so `check` will flag them) |
+
+To add a badge to the top row without touching the config list, fill the `badges_extra` hook (there is a
+`donate_extra` too):
+
+```jinja
+{% block badges_extra %} {{ shield("docs", "latest", "success", link=gh_link("wiki")) }}{% endblock %}
+```
+
+Badge presets: `pypi`, `pypi-downloads`, `python`, `license`, `ci`, `codecov`, `npm`, `github-release`,
+`github-stars`, `pre-commit`, `ruff`, `version`, `modrinth`, `curseforge`, `hacs`, `ha-version`, plus donation presets `kofi`, `buymeacoffee`, `github-sponsors`,
+`patreon`, `paypal`. Add your own under `badges_custom`; set `badges_style: flat-square` (or pass
+`style=` to any badge helper) to restyle them all.
+
+Blocks in `base.md.j2`: `header`, `badges`, `donate`, `toc`, `screenshots`, `install`, `usage`, `extra`,
+`contributing`, `license`. Any packaged partial can be shadowed by a file of the same name under
+`templates/partials/` in the repo (or `~/.config/readwright/templates/` for all your repos).
+
+Image helpers emit plain markdown by default (dark/light pairs use GitHub's
+`#gh-light-mode-only`/`#gh-dark-mode-only` fragments instead of `<picture>`), and only fall back to HTML
+when you ask for something markdown can't do, like a `width=`. Set `screenshots.style: html` to always
+get `<img>`/`<picture>`/`<table>` output, or pass `html=True` to `unsplash()`/`banner:`.
+
+## Configuration
+
+`readme.yaml` in the repo root (or `[tool.readme]` in `pyproject.toml`); see
+[`examples/config-only/readme.yaml`](https://github.com/Garulf/readwright/blob/main/examples/config-only/readme.yaml) for every key,
+annotated. Everything is optional;
+metadata is autodetected from the git remote, the `LICENSE` file and whichever manifest the project
+has: `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `*.csproj`, Gradle (`gradle.properties`
+mod metadata for Minecraft mods), `hacs.json` or a Flow Launcher `plugin.json`. The install section
+adapts to the project type.
+
+```yaml
+template: README.md.j2
+templates: [../shared-readme-templates, "pkg:my_org_templates"]   # extra template search paths
+output: README.md
+strict: false                     # missing screenshot -> error instead of warning
+allow_exec: false                 # let cli_help() run commands during render
+badges_style: flat-square         # optional shields.io style for every badge
+related: [{repo: other-tool, description: Sibling project}]   # for related_repos()
+banner: {unsplash: photo-1518770660439-4636190af475, credit: Alexandre Debiève, user: alexkixa}
+screenshots: {dir: docs/screenshots, width: 720, style: markdown}   # style: html for width/alignment
+badges: [pypi, python, license, {preset: ci, workflow: test.yml}, {shield: {label: Docs, message: latest, color: success}}]
+badges_custom:
+  discord: {label: Discord, message: chat, color: 5865F2, link: https://discord.gg/xyz}
+donate: [kofi, github-sponsors]
+donate_handles: {kofi: yourname, github-sponsors: yourname}
+project: {name: ..., owner: ..., repo: ..., tagline: ..., pypi: ..., npm: ..., license: ..., ci_workflow: ...}
+vars: {anything: you like}
+```
+
+Put the values you repeat across repos (donation handles, owner, custom badges) in
+`~/.config/readwright/config.yaml`; `readwright init` bakes them into each new `readme.yaml` so rendering
+stays reproducible in CI. `readwright render --user-config` merges them ad hoc.
+
+## pre-commit and GitHub Actions
+
+```yaml
+# .pre-commit-config.yaml
+- repo: https://github.com/Garulf/readwright
+  rev: v0.3.0
+  hooks:
+    - id: readwright-check
+```
+
+```yaml
+# .github/workflows/ci.yml
+- uses: Garulf/readwright@v0.3.0
+  with:
+    mode: check     # or render
+```
+
+## Contributing
+
+Issues and pull requests are welcome at [Garulf/readwright](https://github.com/Garulf/readwright).
+
+## License
+
+MIT

readwright-0.3.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+readwright/__init__.py,sha256=HaXVzfv6KcWFsLaJPHypg_mZeISc5A7ydYsxQA2XXjI,214
+readwright/badges.py,sha256=vE4cXgI3Zau19rhM-qgcKJoKve_71AypZzpm_WgYF1Y,9898
+readwright/changelog.py,sha256=O48rB0pQD1Mh3kEHDbalOEIAl-3SNXpOVR7aNRip2t8,1529
+readwright/cli.py,sha256=FfPLfzuStjt4NvSJiBs4_KHCISUz94Zk_lLdsvBDwe0,13401
+readwright/config.py,sha256=-L8OC_knksAGG3ORZ8TMTZSzYr4SXP26OhZs_4I-jl4,7226
+readwright/helpers.py,sha256=R0RJDWFtn0ncqG8n6BtZeRL0jJQdggbDteKyp-tP-pY,19458
+readwright/images.py,sha256=curlWYn4Xo7Nbg_h-pNKxldVuxy5NkJOZyv2Fmy90uM,8251
+readwright/metadata.py,sha256=QQM8mjNsjUp6ehwkEOZvhaKd9kbl3gV0Gk9Pqb3y-DA,8903
+readwright/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+readwright/renderer.py,sha256=4iVMQKvzfUdDv0gJBB0t2aWPglp38Cj0PSqLkufJgfo,6307
+readwright/toc.py,sha256=oGsWLbmtif-M3yZQs1abtGXaXbqaCKTOsF-4Olu8R5g,1952
+readwright/templates/base.md.j2,sha256=ch8eH2sFAArMTDUi1F5rKUuGW9YSYl2oP9swtCSroSE,735
+readwright/templates/partials/badges.md.j2,sha256=m6Z1_q9jEm8eJ81Gx74pGJttYLNA8wHUJ4wybYvDDbo,16
+readwright/templates/partials/contributing.md.j2,sha256=8853IRNvgBERHkmYQhZBdSRjtIb3c2laFdaJPDSocWA,200
+readwright/templates/partials/donate.md.j2,sha256=K1TbEtzJ4LhcHAEam5tyi4ssjSDvISWoq82g7kczsSI,23
+readwright/templates/partials/header.md.j2,sha256=OVQ1li9nLUFx3reJJwT1pVIQPQ3fZzni3XxYHq6HQy4,145
+readwright/templates/partials/install.md.j2,sha256=Ae7K12msy0JHLKkkRBovPpyg2nTaRVYF4pcH-EBFGSw,1484
+readwright/templates/partials/license.md.j2,sha256=sUzggovdgtZOtjHAHjLtBVQjL7aPjwwA05q5dL5pb6U,71
+readwright/templates/partials/screenshots.md.j2,sha256=nprlIDKHyenVS81cajlbIOH1GXzgV_0gAsC4kdDw01E,75
+readwright/templates/partials/usage.md.j2,sha256=Hq5j8xjkRVf2DnEsYZldLSEyF7z4HOyAjKHmt6y7Hzs,70
+readwright-0.3.0.dist-info/METADATA,sha256=ru5zN8OKG-_RgxwOvc3e2Mj9_OQ8WDhqDuW2X0iQK4g,9536
+readwright-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+readwright-0.3.0.dist-info/entry_points.txt,sha256=0ZMlTqX7wSLP9IJQWCxeGHapWofxf-yQAYpEHtn7pVY,50
+readwright-0.3.0.dist-info/licenses/LICENSE,sha256=xeDKZZcHQHHbqoXnQ-2V__i7DdZGKhlpCOiVmPDTauE,1063
+readwright-0.3.0.dist-info/RECORD,,

readwright-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

readwright-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+readwright = readwright.cli:app

readwright-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Garulf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.