Docs: add a tip for checking fragments will render in Sphinx
Opened this issue · 0 comments
ncoghlan commented
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:
- Move the
changelog.d
folder under your Sphinx docs folder (sotoctree
directives can access it) - 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)