rtfc 0.1.0__tar.gz → 0.2.0__tar.gz

{rtfc-0.1.0 → rtfc-0.2.0}/.github/workflows/ci.yml

@@ -31,7 +31,7 @@ jobs:
 
       - 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 }}
 
@@ -53,6 +53,7 @@ jobs:
         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 docs
@@ -65,8 +66,7 @@ jobs:
         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
+        working-directory: ./docs
 
   build:
     name: Build project

{rtfc-0.1.0 → rtfc-0.2.0}/.gitignore

@@ -197,9 +197,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   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, 
+#   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

{rtfc-0.1.0 → rtfc-0.2.0}/.readthedocs.yml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.14"
+    python: '3.14'
   # https://docs.readthedocs.com/platform/stable/build-customization.html#install-dependencies-with-uv
   jobs:
     pre_create_environment:

rtfc-0.2.0/.yamlfmt.yaml

@@ -0,0 +1,5 @@
+formatter:
+  type: basic
+  retain_line_breaks_single: true
+  scan_folded_as_literal: true
+  force_quote_style: single

{rtfc-0.1.0 → rtfc-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rtfc
-Version: 0.1.0
+Version: 0.2.0
 Author-email: Victorien <contact@vctrn.dev>
 License-Expression: MIT
 License-File: LICENSE
@@ -28,13 +28,13 @@ rtfc
 
 |Pythons| |PyPI| |Docs| |Ruff|
 
-.. |Pythons| image:: https://img.shields.io/pypi/pyversions/rdfm.svg
+.. |Pythons| image:: https://img.shields.io/pypi/pyversions/rtfc.svg
   :alt: Supported Python versions
-  :target: https://pypi.org/project/rdfm/
+  :target: https://pypi.org/project/rtfc/
 
-.. |PyPI| image:: https://img.shields.io/pypi/v/rdfm.svg
+.. |PyPI| image:: https://img.shields.io/pypi/v/rtfc.svg
   :alt: PyPI - Version
-  :target: https://pypi.org/project/rdfm/
+  :target: https://pypi.org/project/rtfc/
 
 .. |Docs| image:: https://img.shields.io/readthedocs/rtfc.svg
   :alt: Documentation status
@@ -110,7 +110,7 @@ Validate the configuration and the entries, typically in CI:
     $ rtfc check
     OK: 1 valid entries
 
-On release, combine the entries into the changelog. The version block is
+On release, combine the entries into the changelog. The release notes are
 inserted after the marker, and the entry files are deleted:
 
 .. code:: console

{rtfc-0.1.0 → rtfc-0.2.0}/README.rst

@@ -4,13 +4,13 @@ rtfc
 
 |Pythons| |PyPI| |Docs| |Ruff|
 
-.. |Pythons| image:: https://img.shields.io/pypi/pyversions/rdfm.svg
+.. |Pythons| image:: https://img.shields.io/pypi/pyversions/rtfc.svg
   :alt: Supported Python versions
-  :target: https://pypi.org/project/rdfm/
+  :target: https://pypi.org/project/rtfc/
 
-.. |PyPI| image:: https://img.shields.io/pypi/v/rdfm.svg
+.. |PyPI| image:: https://img.shields.io/pypi/v/rtfc.svg
   :alt: PyPI - Version
-  :target: https://pypi.org/project/rdfm/
+  :target: https://pypi.org/project/rtfc/
 
 .. |Docs| image:: https://img.shields.io/readthedocs/rtfc.svg
   :alt: Documentation status
@@ -86,7 +86,7 @@ Validate the configuration and the entries, typically in CI:
     $ rtfc check
     OK: 1 valid entries
 
-On release, combine the entries into the changelog. The version block is
+On release, combine the entries into the changelog. The release notes are
 inserted after the marker, and the entry files are deleted:
 
 .. code:: console

{rtfc-0.1.0 → rtfc-0.2.0}/changelog/entry.rst.jinja

@@ -1,4 +1,4 @@
 {% set refs = [] %}
 {% if metadata.gh_issue %}{% set _ = refs.append("Issue :issue:`%s`" % metadata.gh_issue) %}{% endif %}
 {% if metadata.gh_pr %}{% set _ = refs.append("PR :pr:`%s`" % metadata.gh_pr) %}{% endif %}
-{{ content }}{% if refs %} ({{ refs | join(", ") }}){% endif %}
+{{ content }}{% if refs %} ({{ refs | join(", ") }}).{% endif %}

rtfc-0.2.0/docs/source/changelog.rst

@@ -0,0 +1,25 @@
+Changelog
+=========
+
+.. rtfc-unreleased::
+
+   These changes are not yet released and are under active development.
+
+.. rtfc-insert
+
+v0.2.0 (2026-08-29)
+-------------------
+
+Features
+~~~~~~~~
+
+- Add the :commands:command:`export <rtfc-export>` command, exporting entries as markdown through the project's sphinx build.
+  See :ref:`configuration` for setup.
+
+v0.1.0 (2026-08-06)
+-------------------
+
+Features
+~~~~~~~~
+
+- Initial release.

rtfc-0.2.0/docs/source/cli.rst

@@ -0,0 +1,21 @@
+.. _cli:
+
+Command line interface
+======================
+
+All commands require a valid :ref:`configuration <configuration>` in the
+current working directory.
+
+.. argparse::
+   :module: rtfc._cli
+   :func: _docs_parser
+   :prog: rtfc
+
+Environment variables
+---------------------
+
+.. envvar:: EDITOR
+
+   The editor ``rtfc new`` opens the created entry in, when ``--content`` is
+   not given. When unset, the entry is created with a placeholder content
+   to edit afterwards.

{rtfc-0.1.0 → rtfc-0.2.0}/docs/source/conf.py

@@ -3,13 +3,19 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+from textwrap import indent
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'rtfc'
-copyright = '2026-%Y, Victorien'
-author = 'Victorien'
-release = '0.1.0'
+project = "rtfc"
+copyright = "2026-%Y, Victorien"
+author = "Victorien"
+release = "0.2.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -25,11 +31,11 @@ extensions = [
 
 rtfc_config_directory = "../.."
 
-templates_path = ['_templates']
 exclude_patterns = []
 
 intersphinx_mapping = {
     "packaging": ("https://packaging.python.org/en/latest", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
 }
 
 issues_github_path = "Viicos/rtfc"
@@ -37,23 +43,29 @@ issues_github_path = "Viicos/rtfc"
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+html_baseurl = "https://rtfc.readthedocs.io/en/latest/"
 html_theme = "furo"
-html_static_path = ['_static']
 html_theme_options = {
     "source_repository": "https://github.com/Viicos/rtfc/",
     "source_branch": "main",
     "source_directory": "docs/source/",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/Viicos/rtfc/",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
 }
 
 
 # -- Custom directives --------------------------------------------------------
 
-from textwrap import indent
-
-from docutils import nodes
-from sphinx.application import Sphinx
-from sphinx.util.docutils import SphinxDirective
-
 
 def _pyproject_variant(toml: str) -> str:
     """Derive the ``pyproject.toml`` form of an ``rtfc.toml`` example."""
@@ -88,6 +100,3 @@ class RtfcConfigExample(SphinxDirective):
 
 def setup(app: Sphinx) -> None:
     app.add_directive("rtfc-config-example", RtfcConfigExample)
-
-    # Workaround for https://github.com/sphinx-doc/sphinx-argparse/issues/98:
-    app.extensions["sphinxarg.ext"].parallel_read_safe = False

{rtfc-0.1.0 → rtfc-0.2.0}/docs/source/configuration.rst

@@ -11,7 +11,7 @@ Relative paths are resolved against the directory the configuration is discovere
 .. confval:: changelog
    :type: path
 
-   The changelog file version blocks are inserted into on release. Required;
+   The changelog file the release notes are inserted into on release. Required;
    the file must exist and contain the insert marker comment
    (``.. rtfc-insert`` for the rst format).
 
@@ -96,12 +96,12 @@ Relative paths are resolved against the directory the configuration is discovere
    :type: string
    :default: the template below
 
-   The Jinja template rendering a whole version block. The template receives:
+   The Jinja template rendering the whole release notes of a version. The template receives:
 
    ``header``
        The already-formatted version header.
    ``entries``
-       All the entries of the block.
+       All the entries of the release notes.
    ``sections``
        The entries grouped by section: the unsectioned group first, then the
        configured sections in order. Each group has ``id``, ``label``
@@ -146,7 +146,7 @@ Relative paths are resolved against the directory the configuration is discovere
    :type: path
    :default: unset
 
-   A file containing the version block template, as an alternative to
+   A file containing the release notes template, as an alternative to
    :confval:`render.template`.
 
    .. rtfc-config-example::
@@ -179,6 +179,42 @@ Relative paths are resolved against the directory the configuration is discovere
       [rtfc.render]
       entry_template_file = "entry.rst.jinja"
 
+.. confval:: export.<exporter>.engine
+   :type: table
+
+   :ref:`Exporters <export>`, converting the release notes to another format,
+   are configured with one table per exporter id. The ``engine`` table selects
+   and configures the format engine used to convert the format-specific syntax
+   of the entries; its ``name`` key discriminates the engine and its remaining
+   keys. The built-in ``markdown``, ``github-markdown`` and ``gitlab-markdown``
+   exporters all support the ``sphinx`` engine.
+
+   .. rtfc-config-example::
+
+      [rtfc.export.markdown.engine]
+      name = "sphinx"
+      sphinx_directory = "docs/source"
+
+.. confval:: export.<exporter>.engine.sphinx_directory
+   :type: path
+
+   The Sphinx source directory (containing :file:`conf.py`). Required.
+
+.. TODO use  ``:confval:sphinx:html_baseurl`` once https://github.com/sphinx-doc/sphinx/issues/14117 is fixed.
+
+.. confval:: export.<exporter>.engine.base_url
+   :type: string
+   :default: the ``html_baseurl`` Sphinx configuration value
+
+   Absolute URL of the published documentation, used to resolve relative links.
+
+   .. rtfc-config-example::
+
+      [rtfc.export.markdown.engine]
+      name = "sphinx"
+      sphinx_directory = "docs/source"
+      base_url = "https://rtfc.readthedocs.io/en/latest"
+
 .. seealso::
 
    The :ref:`sphinx extension <sphinx_extension>` has its own configuration

rtfc-0.2.0/docs/source/export.rst

@@ -0,0 +1,88 @@
+.. _export:
+
+Exporting release notes
+=======================
+
+Besides being inserted into the changelog document, the release notes of a
+version can be *exported* to another format (typically markdown).
+
+This is particularly useful when publishing release notes in separate places,
+e.g. `GitHub releases <https://docs.github.com/en/repositories/releasing-projects-on-github>`_.
+
+rtfc supports multiple exporters (see below). The exporter to use must first be
+:confval:`configured <export.<exporter>.engine>`, e.g. the ``github-markdown``
+exporter with the ``sphinx`` format engine:
+
+.. rtfc-config-example::
+
+   [rtfc.export.github-markdown.engine]
+   name = "sphinx"
+   sphinx_directory = "docs/source"
+
+The :commands:command:`export <rtfc-export>` command can then be used to produce
+the exported release notes:
+
+.. code-block:: console
+
+    $ rtfc export github-markdown --version 1.2.0 > release-notes.md
+
+Run the export *before* ``rtfc build``, which deletes the entry files on
+release.
+
+Exporters and format engines
+----------------------------
+
+Exporters are responsible for converting changelog entries (present in your
+:confval:`entry directory <directory>`) into a single text block, that can then
+be published separately. An exporter is defined for a specific
+:ref:`documentation format <documentation-format>`, and delegates the conversion
+of the format-specific syntax to a *format engine*.
+
+A *format engine* encapsulates the logic required to run your documentation engine/framework.
+While :ref:`formats <documentation-format>` are agnostic of the documentation framework [#f1]_,
+exporters need to use the semantics of your documentation engine, for example to resolve
+references as HTML links.
+
+rtfc provides hree built in exporters:
+
+``markdown``
+    `CommonMark <https://spec.commonmark.org/>`_ output. Admonitions are
+    rendered as block quotes opened by a bold label.
+``github-markdown``
+    `GitHub Flavored Markdown <https://github.github.com/gfm/>`_ output,
+    extended with the GitHub markdown extensions. Suitable for
+    `GitHub releases <https://docs.github.com/en/repositories/releasing-projects-on-github>`_.
+``gitlab-markdown``
+    `GitLab Flavored Markdown <https://docs.gitlab.com/user/markdown/>`_ output. Suitable for
+    `GitHub releases <https://docs.gitlab.com/user/project/releases/>`_.
+
+All three support the ``sphinx`` format engine.
+
+The sphinx engine
+-----------------
+
+The ``sphinx`` engine requires `Sphinx <https://www.sphinx-doc.org/>`_ to be
+installed, and converts the Sphinx-flavored rst of the entries by building
+them through the project's own Sphinx documentation (i.e. by using the project's
+:ref:`Sphinx configuration <sphinx:build-config>`). Headings, paragraphs,
+lists, code blocks, inline markup, links, images and admonitions are
+supported. Other nodes are left as is. Relative links are joined onto
+the :confval:`base URL <export.<exporter>.engine.base_url>` of the
+published documentation.
+
+.. rtfc-config-example::
+
+   [rtfc.export.github-markdown.engine]
+   name = "sphinx"
+   sphinx_directory = "docs/source"
+   base_url = "https://rtfc.readthedocs.io/en/latest"
+
+.. note::
+
+   Each export runs a Sphinx build of the whole project, as resolving
+   cross-references requires the complete environment.
+
+.. rubric:: Footnotes
+
+.. [#f1] For instance, the builtin ``rst`` format doesn't necessarily assume
+         `Sphinx <https://www.sphinx-doc.org/>`_ is used.

{rtfc-0.1.0 → rtfc-0.2.0}/docs/source/index.rst

@@ -16,4 +16,5 @@ rtfc documentation
    configuration
    cli
    sphinx
+   export
    changelog

{rtfc-0.1.0 → rtfc-0.2.0}/docs/source/usage.rst

@@ -29,6 +29,21 @@ The ``[tool.rtfc]`` table can be used in the :file:`pyproject.toml` of your proj
 
 ``changelog`` is the only required configuration value. See :ref:`configuration` for more details.
 
+.. _documentation-format:
+
+Documentation format
+--------------------
+
+rtfc is not tied to a documentation framework: changelog entries are written
+in the documentation format of your project, and rtfc only combines them
+(their content is never parsed). The :confval:`format` configuration value
+selects the format, which determines the structure rtfc produces (headings,
+list items, the insert marker comment). reStructuredText (``rst``) is built in
+and the default. Other formats can be provided by third-party packages, through
+the ``rtfc.formats`` :ref:`entry point group <packaging:entry-points>`.
+
+The examples below use the default ``rst`` format.
+
 Setting up a project
 --------------------
 
@@ -55,25 +70,26 @@ Besides the configuration file, rtfc expects two things to exist:
 Workflow
 --------
 
-Create a changelog entry along the changes of a pull request. When run from
-a terminal, missing values are prompted for, and the entry is opened in
-:envvar:`EDITOR`:
+Create a changelog entry along the changes of a pull request with the
+:commands:command:`new <rtfc-new>` command. When run from a terminal,
+missing values are prompted for, and the entry is opened in :envvar:`EDITOR`:
 
 .. code-block:: console
 
     $ rtfc new --section bugfix --meta gh_issue=123 --content "Fix a bug."
     Created changelog/d0592011.bugfix.rtfc
 
-Validate the configuration and all entries, typically in CI:
+Validate the configuration and all entries with the :commands:command:`check <rtfc-check>`
+command, typically in CI:
 
 .. code-block:: console
 
     $ rtfc check
     OK: 3 valid entries
 
-On release, combine the entries into the changelog. The version block is
-inserted after the marker and the entry files are deleted. Use ``--dry-run``
-first to preview the block without touching anything:
+On release, combine the entries into the changelog with the :commands:command:`build <rtfc-build>`
+command. The release notes are inserted after the marker and the entry files are deleted. Use
+``--dry-run`` first to preview the release notes without touching anything:
 
 .. code-block:: console
 
@@ -81,6 +97,9 @@ first to preview the block without touching anything:
     $ rtfc build --version 1.2.0
     Updated docs/source/changelog.rst
 
+Entries can also be :ref:`exported <export>` in alternative formats, e.g. as
+markdown for GitHub or GitLab release notes.
+
 See the :ref:`command line interface reference <cli>` for all options.
 
 

{rtfc-0.1.0 → rtfc-0.2.0}/prek.toml

@@ -1,7 +1,7 @@
 [[repos]]
 repo = "builtin"
 hooks = [
-  { id = "end-of-file-fixer", args = ["--fix"] },
+  { id = "end-of-file-fixer" },
   { id = "trailing-whitespace" },
 ]
 

{rtfc-0.1.0 → rtfc-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rtfc"
-version = "0.1.0"
+version = "0.2.0"
 authors = [
     {name = "Victorien", email = "contact@vctrn.dev"}
 ]
@@ -35,6 +35,9 @@ dependencies = [
 [project.scripts]
 rtfc = "rtfc._cli:main"
 
+[project.entry-points."sphinx.builders"]
+rtfc-export = "rtfc._export._sphinx"
+
 [dependency-groups]
 dev = [
     "pyright",
@@ -95,6 +98,7 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
+"docs/source/conf.py" = ["E501"]
 "src/rtfc/_cli.py" = ["T20"]
 
 [tool.ruff.lint.isort]
@@ -106,8 +110,14 @@ strict = true
 
 [tool.rtfc]
 changelog = "docs/source/changelog.rst"
+
 [tool.rtfc.render]
 entry_template_file = "changelog/entry.rst.jinja"
+
+[tool.rtfc.export.github-markdown.engine]
+name = "sphinx"
+sphinx_directory = "docs/source"
+
 [tool.rtfc.metadata]
 gh_issue = {type = "integer"}
 gh_pr = {type = "integer"}

{rtfc-0.1.0 → rtfc-0.2.0}/src/rtfc/_changelog.py

@@ -1,8 +1,8 @@
-"""Assembly of version blocks into the changelog document.
+"""Assembly of release notes into the changelog document.
 
 The changelog document must contain an insert marker (a format comment, e.g.
-``.. rtfc-insert`` for rst): released version blocks are inserted right after
-it, newest first.
+``.. rtfc-insert`` for rst). The release notes of released versions are inserted
+right after it.
 """
 
 from __future__ import annotations
@@ -21,12 +21,12 @@ def _with_trailing_newline(lines: list[str]) -> str:
     return text if text.endswith("\n") else text + "\n"
 
 
-def insert_version(changelog: str, block: str, *, fmt: Format) -> str:
-    """Insert a released version block right after the insert marker.
+def insert_version(changelog: str, notes: str, *, fmt: Format) -> str:
+    """Insert the release notes of a version right after the insert marker.
 
     Args:
         changelog: The current changelog text.
-        block: The rendered version block.
+        notes: The rendered release notes.
         fmt: The documentation format.
 
     Raises:
@@ -39,7 +39,7 @@ def insert_version(changelog: str, block: str, *, fmt: Format) -> str:
             rest = lines[index + 1 :]
             while rest and not rest[0].strip():
                 rest.pop(0)
-            inserted = [*lines[: index + 1], "", *block.split("\n")]
+            inserted = [*lines[: index + 1], "", *notes.split("\n")]
             if rest:
                 inserted += ["", *rest]
             return _with_trailing_newline(inserted)