openstack/reno
Code Issues Proposed changes
master
reno/doc/source/user/sphinxext.rst
Akihiro Motoki ff2ca65e5c Clean up rendered HTML with openstackdocstheme 
After migrating to openstackdocstheme, there are several points
to be improved in the rendered HTML files.

* Cleanup unnecessary vertical lines for quote blocks.
  Existing quote blocks are actually not intended and
  leading extra spaces cause this.
  This commit removes unnecessary leading spaces.
* Some quote blocks are converted into definition lists
  to clean up vertical lines for quote blocks.
* Use code-block for better code highlighting.
* Specify maxdepth in user/index toctree.

Change-Id: I9add5a317718e97abce15b5ddbfa3d1208a01570
2017-07-19 09:44:08 +00:00

2.6 KiB
Raw Permalink Blame History

Sphinx Extension

In addition to the command line tool, reno includes a Sphinx extension for incorporating release notes for a project in its documentation automatically.

Enable the extension by adding 'reno.sphinxext' to the extensions list in the Sphinx project conf.py file.

The release-notes directive accepts the same inputs as the report subcommand, and inserts the report inline into the current document where Sphinx then processes it to create HTML, PDF, or other output formats.

If the directive has a body, it is used to create a title entry with = over and under lines (the typical heading style for the top-level heading in a document).

Options:

branch

The name of the branch to scan. Defaults to the current branch.

reporoot

The path to the repository root directory. Defaults to the directory where sphinx-build is being run.

relnotessubdir

The path under reporoot where the release notes are. Defaults to releasenotes.

notesdir

The path under relnotessubdir where the release notes are. Defaults to notes.

version

A comma separated list of versions to include in the notes. The default is to include all versions found on branch.

collapse-pre-releases

A flag indicating that notes attached to pre-release versions should be incorporated into the notes for the final release, after the final release is tagged.

earliest-version

A string containing the version number of the earliest version to be included. For example, when scanning a branch, this is typically set to the version used to create the branch to limit the output to only versions on that branch.

ignore-notes

A string containing a comma-delimited list of filenames or UIDs for notes that should be ignored by the scanner. It is most useful to set this when a note is edited on the wrong branch, making it appear to be part of a release that it is not.

Examples

The release notes for the "current" branch, with "Release Notes" as a title.

.. release-notes:: Release Notes

The release notes for the "stable/liberty" branch, with a separate title.

=======================
 Liberty Release Notes
=======================

.. release-notes::
   :branch: stable/liberty

The release notes for version "1.0.0".

.. release-notes:: 1.0.0 Release Notes
   :version: 1.0.0