1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
==================
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.
.. rst:directive:: release-notes
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.
.. code-block:: rest
.. release-notes:: Release Notes
The release notes for the "stable/liberty" branch, with a separate
title.
.. code-block:: rest
=======================
Liberty Release Notes
=======================
.. release-notes::
:branch: stable/liberty
The release notes for version "1.0.0".
.. code-block:: rest
.. release-notes:: 1.0.0 Release Notes
:version: 1.0.0
|
