nedbat / scriv

Changelog management tool
https://scriv.readthedocs.io
Apache License 2.0
260 stars 29 forks source link

Docs: add a tip for checking fragments will render in Sphinx #136

Open ncoghlan opened 2 weeks ago

ncoghlan commented 2 weeks ago

I just set this up myself, and it seemed like it would be generally useful enough to be worth mentioning somewhere in the scriv docs:

  1. Move the changelog.d folder under your Sphinx docs folder (so toctree directives can access it)
  2. Add a :hidden: + :glob: .. toctree:: directive somehow that renders the unreleased fragments without linking them

For example, have this in pyproject.toml:

[tool.scriv]
fragment_directory = "docs/changelog.d"

and this in the Sphinx page that includes the CHANGELOG.rst file:

.. Syntax check the changelog fragments

.. toctree::
   :hidden:
   :glob:

   changelog.d/*

.. Include the scriv-generated changelog details

.. include:: ../CHANGELOG.rst

This should also work for markdown fragments (assuming Sphinx is set up to render markdown files)