rtfc 0.1.0__tar.gz

rtfc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '**'
+  pull_request: {}
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Run tests with pytest
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.11', '3.12', '3.13', '3.14', '3.15']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true # zizmor: ignore[cache-poisoning] (Job does not produce release artifacts and does not have sensitive permissions)
+
+      - name: Install tox
+        run: uv tool install --managed-python --python 3.13 tox --with tox-uv --with tox-gh
+  
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install --managed-python ${{ matrix.python-version }}
+
+      - name: Test with tox
+        run: tox run
+        env:
+          TOX_GH_MAJOR_MINOR: ${{ matrix.python-version }}
+          UV_PYTHON_DOWNLOADS: never
+
+  docs:
+    name: Build and check documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.14
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: '3.14'
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Lint docs with sphinx-lint
+        run: |
+          uv run sphinx-lint docs
+
+      - name: Build docs and check the integrity of external links
+        run: |
+          uv run sphinx-build --builder linkcheck --fail-on-warning "source" "build"
+          uv run sphinx-build --builder html --fail-on-warning "source" "build"
+        working-directory:
+          ./docs
+
+  build:
+    name: Build project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: false
+
+      - run: uv sync --no-install-project --only-group build
+
+      - name: Build library
+        run: uv run --no-sync python -m build --installer uv
+
+      - run: ls -lh dist/
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: pypi_files
+          path: dist
+
+  release:
+    needs: [tests, docs, build]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    environment: release
+
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: false
+
+      - run: uv sync --no-install-project --only-group build
+
+      - name: Get pydantic dist artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: pypi_files
+          path: dist
+
+      - name: Test artifacts integrity
+        run: |
+          for whl in dist/*.whl; do unzip -qt "$whl"; done
+          uv run --no-sync twine check --strict dist/*
+
+      - name: Upload package to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/

rtfc-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,83 @@
+name: lint
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '**'
+  pull_request: {}
+
+permissions:
+  contents: read
+
+jobs:
+  prek:
+    name: Run prek pre-commit hooks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: j178/prek-action@4e14d07f9231acabce116ccfca13b13dd9755ece # v3.0.0
+
+  ruff-format:
+    name: Check code formatting with Ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.14
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: '3.14'
+          enable-cache: true # zizmor: ignore[cache-poisoning] (Job does not produce release artifacts and does not have sensitive permissions)
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run Ruff formatter
+        run: uv run ruff format --diff
+
+  ruff-check:
+    name: Check code linting with Ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.14
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: '3.14'
+          enable-cache: true # zizmor: ignore[cache-poisoning] (Job does not produce release artifacts and does not have sensitive permissions)
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run Ruff formatter
+        run: uv run ruff check --output-format=github
+
+  typecheck:
+    name: Run typechecking with pyright
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.14
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: '3.14'
+          enable-cache: true # zizmor: ignore[cache-poisoning] (Job does not produce release artifacts and does not have sensitive permissions)
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run pyright
+        run: uv run pyright

rtfc-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

rtfc-0.1.0/.readthedocs.yml

@@ -0,0 +1,31 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.com/platform/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+  # https://docs.readthedocs.com/platform/stable/build-customization.html#install-dependencies-with-uv
+  jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+  - epub

rtfc-0.1.0/DESIGN.md

@@ -0,0 +1,188 @@
+# rtfc — design plan
+
+rtfc ("read the freaking changelog") is a Python tool to manage changelogs and versioning,
+similar in spirit to towncrier. Changelog entries live as individual files in a
+configurable directory and are combined into a changelog document on release.
+Primarily targets Python documentation (sphinx/rst first), but designed to be
+extensible to other formats (e.g. mkdocs markdown).
+
+Status: draft — iterating.
+
+## 1. Entry file format
+
+**Decision: TOML frontmatter + raw body.** One file per entry, structured header and
+an **opaque** body, separated by a `+++` delimiter:
+
+```
++++
+date = 2025-08-01
+nonce = "k3jf9a"
+section = "bugfix"          # optional, may be absent (null)
+
+[metadata]                  # optional, free-form
+gh_issue = 123
+is_backport = true
++++
+Fix a bug where :meth:`~pydantic.BaseModel.model_dump` would crash on
+recursive references. Multi-line, arbitrary rst — never parsed by rtfc.
+```
+
+Rationale, vs the alternatives considered:
+
+- **Pure TOML/JSON/YAML**: multiline content in TOML (`"""..."""` escaping) or YAML
+  (indentation-sensitive block scalars) is annoying to write and review in PRs.
+  JSON is a non-starter for humans.
+- **Native `.rst` with docinfo field lists**: bare docutils on a body containing
+  sphinx-specific syntax doesn't hard-crash, but emits "Unknown interpreted text
+  role" / "Unknown directive type" system messages and mangles the parse. Also
+  needs a different metadata convention per docs format, and nested `metadata`
+  doesn't map onto rst field lists. Dead end.
+- **TOML frontmatter** gives: real nested mappings for `metadata`, real date types,
+  trivial parsing (split on delimiter, `tomllib` the header, keep the rest
+  verbatim), and the body stays raw text in the target docs format. The body is
+  only ever interpreted by sphinx itself, after assembly into `changelog.rst`.
+
+Parsing: split on the delimiter, parse header with `tomllib`, body kept verbatim.
+
+Filename: `{nonce}.rtfc` — the nonce (generated by `rtfc new`) guarantees filenames
+can't collide across concurrent PRs. Extension TBD (see open questions); cost of a
+dedicated extension is no editor highlighting for the body.
+
+Note: `tomllib` is stdlib from 3.11 — either bump `requires-python` to `>=3.11`
+(recommended for a new tool) or depend on `tomli` for 3.10.
+
+## 2. Core data model
+
+```python
+@dataclass
+class Entry:
+    date: date
+    nonce: str
+    section: str | None       # must be a key of configured sections, or None
+    metadata: dict[str, Any]  # free-form
+    content: str              # raw body, never parsed
+```
+
+Validation at load time: mandatory fields present (`date`, `nonce`), `section`
+(if set) exists in config, dates parseable. `rtfc check` runs this in CI.
+
+Terminology note: "section" here is what the original brief also called "type"
+(the entry's category: feature, bugfix, ...). Naming TBD.
+
+## 3. Configuration
+
+Discovery: `rtfc.toml` if present (takes priority), else `[tool.rtfc]` in
+`pyproject.toml`. Loaded into frozen dataclasses (no pydantic dependency needed
+for a tool this size).
+
+```toml
+[tool.rtfc]
+directory = "changelog.d"
+changelog = "docs/changelog.rst"
+format = "rst"                       # entry point name of the format plugin
+
+# defaults if omitted; declaration order = output order
+[tool.rtfc.sections.feature]
+label = "Features"
+
+[tool.rtfc.sections.bugfix]
+label = "Bug fixes"
+
+[tool.rtfc.render]
+sort = ["date", "metadata.gh_issue"]   # sort key within a section
+flat = false                            # true: ignore sections, one flat list
+entry_template = "{{ content }}{% if metadata.gh_issue %} (:gh:`{{ metadata.gh_issue }}`){% endif %}"
+```
+
+Templating: **Jinja2**, per-entry only. Standard, known from towncrier; inventing a
+mini-language would be worse. The template receives `content`, `date`, `section`,
+`metadata`. Section headers and version headers are produced by the format plugin,
+not templates (version header non-configurable for now: just the version number
+provided on the command line).
+
+Entries with `section = None` in sectioned mode: rendered in an unlabeled group
+before the first section (could become configurable later).
+
+## 4. Format plugins
+
+Small protocol; rst implementation built in; third parties register via the
+`rtfc.formats` entry-point group:
+
+```python
+class Format(Protocol):
+    name: str
+    def version_header(self, version: str, date: date) -> str: ...   # underlined title for rst
+    def section_header(self, label: str) -> str: ...
+    def render_entry(self, rendered_text: str) -> str: ...           # "- " bullet + indent continuation lines
+    def markers(self) -> tuple[str, str]: ...                        # comment syntax for insertion/unreleased markers
+```
+
+The plugin never parses entry bodies — it only wraps already-rendered text in
+format-level structure. Keeps a future mkdocs/markdown implementation trivial.
+
+## 5. Assembly into the changelog file
+
+The changelog file contains an insertion marker (rst comment):
+
+```rst
+Changelog
+=========
+
+.. rtfc-insert
+
+v1.2.0 (2025-07-01)
+-------------------
+...
+```
+
+- `rtfc build --version 1.3.0` — collects entries, renders the version block,
+  inserts it right after the marker, **deletes** the entry files.
+- `rtfc build --unreleased` — renders the same block titled "Unreleased", wrapped
+  in begin/end markers (`.. rtfc-unreleased-start` / `-end`) so re-running
+  **replaces** the previous unreleased block idempotently; deletes nothing.
+  A release build first removes any existing unreleased block.
+- `--draft` — print to stdout instead of writing (useful in CI and for release
+  PR/GitHub-release descriptions).
+
+## 6. CLI
+
+- `rtfc new [--section bugfix] [--meta gh_issue=123]` — generates nonce + today's
+  date, opens `$EDITOR` or takes `--content`.
+- `rtfc build [--version X.Y.Z | --unreleased] [--draft]`
+- `rtfc check` — validate all entries (CI-friendly).
+
+Library: argparse, keeping runtime deps at just `jinja2` (+ `tomli` on 3.10).
+Switch to click only if subcommand UX outgrows it.
+
+## 7. Future exports (design awareness only)
+
+Faithful markdown export (e.g. for GitHub releases) requires sphinx, since
+`` :gh:`123` `` can expand to a link, a section, a table, anything. The
+architecture keeps this open in two ways:
+
+- Entries stay structured until the final render, so an exporter can re-render
+  from `Entry` objects rather than scraping `changelog.rst`.
+- A future sphinx-based export path can build just the changelog doc through
+  sphinx with a text/markdown builder to resolve roles.
+
+Nothing in the core needs to change for either — the renderer produces a
+version-block string; writing it into the changelog file is a separate step, so
+"changelog file is the only output" is not baked into the renderer API.
+
+## 8. Milestones
+
+1. Config loading (`rtfc.toml` / `pyproject.toml`) + entry parser + `Entry`
+   model + `check` — pure, easily tested.
+2. rst format plugin + renderer (sections, sorting, Jinja entry template).
+3. File assembly (markers, unreleased replacement, entry deletion) + `build` CLI.
+4. `rtfc new`, docs, polish; entry-point plugin loading.
+
+## Open questions
+
+1. `section` vs `type` naming for the entry category field.
+2. `.rtfc` extension vs something else for entry files?
+3. Bump to Python ≥3.11 for `tomllib`?
+4. `--unreleased` as a flag on `build` vs a separate command — leaning flag
+   (same logic, one code path).
+5. Delimiter: `+++` (Hugo-style, signals TOML) vs `---` (usually implies YAML) —
+   leaning `+++`.

rtfc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victorien
+
+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.