mirror of
https://github.com/vale981/releases
synced 2025-03-04 17:21:43 -05:00
1st stab at real Sphinx docs hurr
This commit is contained in:
Jeff Forcier
parent
5d0717b7de
commit
053d372fbb
8 changed files with 175 additions and 129 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -2,3 +2,4 @@
|
||||||
*.egg*
|
*.egg*
|
||||||
.*.swp
|
.*.swp
|
||||||
build/
|
build/
|
||||||
|
docs/_build
|
||||||
|
|
|
||||||
139
README.rst
139
README.rst
|
|
@ -1,9 +1,8 @@
|
||||||
=================================
|
.. image:: https://secure.travis-ci.org/bitprophet/releases.png?branch=master
|
||||||
Releases, a Sphinx changelog tool
|
:target: https://travis-ci.org/bitprophet/releases
|
||||||
=================================
|
|
||||||
|
|
||||||
About
|
What is Releases?
|
||||||
=====
|
=================
|
||||||
|
|
||||||
Releases is a `Sphinx <http://sphinx-doc.org>`_ extension designed to help you
|
Releases is a `Sphinx <http://sphinx-doc.org>`_ extension designed to help you
|
||||||
keep a source control friendly, merge friendly changelog file & turn it into
|
keep a source control friendly, merge friendly changelog file & turn it into
|
||||||
|
|
@ -24,128 +23,10 @@ Specifically:
|
||||||
Some background on why this tool was created can be found in `this blog post
|
Some background on why this tool was created can be found in `this blog post
|
||||||
<http://bitprophet.org/blog/2013/09/14/a-better-changelog/>`_.
|
<http://bitprophet.org/blog/2013/09/14/a-better-changelog/>`_.
|
||||||
|
|
||||||
Usage
|
For more documentation, including detailed installation and usage information,
|
||||||
=====
|
please see http://releases.readthedocs.org.
|
||||||
|
|
||||||
Mimic the format seen `in Fabric's changelog
|
.. note::
|
||||||
<https://raw.github.com/fabric/fabric/master/docs/changelog.rst>`_:
|
You can install the `development version
|
||||||
|
<https://github.com/bitprophet/releases/tarball/master#egg=releases-dev>`_
|
||||||
* Install ``releases`` and update your Sphinx ``conf.py`` to include it in the
|
via ``pip install releases==dev``.
|
||||||
``extensions`` list setting: ``extensions = ['releases']``.
|
|
||||||
|
|
||||||
* Also set the ``releases_release_uri`` and ``releases_issue_uri`` top
|
|
||||||
level options - they determine the targets of the issue & release links
|
|
||||||
in the HTML output. Both should have an unevaluated ``%s`` where the
|
|
||||||
release/issue number would go.
|
|
||||||
* See `Fabric's docs/conf.py
|
|
||||||
<https://github.com/fabric/fabric/blob/4afd33e971f1c6831cc33fd3228013f7484fbe35/docs/conf.py#L31>`_
|
|
||||||
for an example.
|
|
||||||
|
|
||||||
* Create a Sphinx document named ``changelog.rst`` with a top-level header
|
|
||||||
followed by a bulleted list.
|
|
||||||
* List items are to be ordered chronologically with the newest ones on top.
|
|
||||||
|
|
||||||
* As you fix issues, put them on the top of the list.
|
|
||||||
* As you cut releases, put those on the top of the list and they will
|
|
||||||
include the issues below them.
|
|
||||||
* Issues with no releases above them will end up in a specially marked
|
|
||||||
"Unreleased" section of the rendered changelog.
|
|
||||||
|
|
||||||
* Bullet list items should use the ``support``, ``feature`` or ``bug``
|
|
||||||
roles to mark issues, or ``release`` to mark a release. These special roles
|
|
||||||
must be the first element in each list item.
|
|
||||||
|
|
||||||
* Line-items that do not start with any issue role will be considered bugs
|
|
||||||
(both in terms of inclusion in releases, and formatting) and, naturally,
|
|
||||||
will not be given a hyperlink.
|
|
||||||
|
|
||||||
* Issue roles are of the form ``:type:`number[ keyword]```. Specifically:
|
|
||||||
|
|
||||||
* ``number`` is used to generate the link to the actual issue in your issue
|
|
||||||
tracker (going by the ``releases_issue_uri`` option). It's used for both
|
|
||||||
the link target & (part of) the link text.
|
|
||||||
* If ``number`` is ``0`` no issue link will be generated. You can use this
|
|
||||||
for items without a related issue.
|
|
||||||
* Keywords are optional and may be one of:
|
|
||||||
|
|
||||||
* ``backported``: Given on *support* or *feature* issues to denote
|
|
||||||
backporting to bugfix releases; such issues will show up in both
|
|
||||||
release types. E.g. placing ``:support:`123 backported``` in your
|
|
||||||
changelog below releases '1.1.1' and '1.2.0' will cause it to appear
|
|
||||||
in both of those releases' lists.
|
|
||||||
* ``major``: Given on bug issues to denote inclusion in feature,
|
|
||||||
instead of bugfix, releases. E.g. placing ``:bug:`22 major``` below
|
|
||||||
releases '1.1.1' and '1.2.0' will cause it to appear in '1.2.0'
|
|
||||||
**only**.
|
|
||||||
|
|
||||||
* Regular Sphinx content may be given after issue roles and will be preserved
|
|
||||||
as-is when rendering. For example, in ``:bug:`123` Fixed a bug, thanks
|
|
||||||
`@somebody`!``, the rendered changelog will preserve/render "Fixed a bug,
|
|
||||||
thanks ``@somebody``!" after the issue link.
|
|
||||||
* Release roles are of the form ``:release:`number <date>```. Do not place any
|
|
||||||
additional content after release roles - it will be ignored.
|
|
||||||
|
|
||||||
Then build your docs; in the rendered output, ``changelog.html`` should show
|
|
||||||
issues grouped by release, as per the above rules. Example: `Fabric's rendered
|
|
||||||
changelog <http://docs.fabfile.org/en/latest/changelog.html>`_.
|
|
||||||
|
|
||||||
Changes
|
|
||||||
=======
|
|
||||||
|
|
||||||
In a fit of irony, Releases is too simple for a full Sphinx doc treatment (or
|
|
||||||
for multiple release lines) and thus doesn't use itself. Here's a by-hand
|
|
||||||
changelog:
|
|
||||||
|
|
||||||
* 2013.11.06: **0.3.0**:
|
|
||||||
|
|
||||||
* Issues #1, #3, #10 - allow using '0' as a dummy issue number, which will
|
|
||||||
result in no issue number/link being displayed. Thanks to Markus
|
|
||||||
Zapke-Gründemann and Hynek Schlawack for patches & discussion.
|
|
||||||
|
|
||||||
* This feature lets you categorize changes that aren't directly related
|
|
||||||
to issues in your tracker. It's an improvement over, and replacement
|
|
||||||
for, the previous "vanilla bullet list items are treated as bugs"
|
|
||||||
behavior.
|
|
||||||
* Said behavior (non-role-prefixed bullet list items turning into
|
|
||||||
regular bugs) is being retained as there's not a lot to gain from
|
|
||||||
deactivating it.
|
|
||||||
|
|
||||||
* 2013.10.04: **0.2.4**:
|
|
||||||
|
|
||||||
* Handful of typos, doc tweaks & addition of a .gitignore file. Thanks to
|
|
||||||
Markus Zapke-Gründemann.
|
|
||||||
* Fix duplicate display of "bare" (not prefixed with an issue role)
|
|
||||||
changelog entries. Thanks again to Markus.
|
|
||||||
* Edited the README/docs to be clearer about how Releases works/operates.
|
|
||||||
* Explicitly documented how non-role-prefixed line items are preserved.
|
|
||||||
* Updated non-role-prefixed line items so they get prefixed with a '[Bug]'
|
|
||||||
signifier (since they are otherwise treated as bugfix items.)
|
|
||||||
|
|
||||||
* 2013.09.16: **0.2.3**:
|
|
||||||
|
|
||||||
* Fix a handful of bugs in release assignment logic.
|
|
||||||
|
|
||||||
* 2013.09.15: **0.2.2**:
|
|
||||||
|
|
||||||
* Python 3 compatibility.
|
|
||||||
|
|
||||||
* 2013.09.15: **0.2.1**:
|
|
||||||
|
|
||||||
* Fixed a stupid bug causing invalid issue hyperlinks.
|
|
||||||
* Added this README.
|
|
||||||
|
|
||||||
* 2013.09.15: **0.2.0**:
|
|
||||||
|
|
||||||
* Basic functionality.
|
|
||||||
|
|
||||||
|
|
||||||
TODO
|
|
||||||
====
|
|
||||||
|
|
||||||
* Tests would be nice.
|
|
||||||
* Possibly add more keywords to allow control over additional edge cases.
|
|
||||||
* Add shortcut format option for the release/issue URI settings - GitHub users
|
|
||||||
can just give their GitHub acct/repo and we will fill in the rest.
|
|
||||||
* Maybe say pre-1.0 releases consider all bugs 'major' (so one can e.g. put out
|
|
||||||
an 0.4.0 which is all bugfixes). Iffy because what if you *wanted* regular
|
|
||||||
feature-vs-bugfix releases pre-1.0? (which is common.)
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,9 @@
|
||||||
|
# Task runner
|
||||||
invoke>=0.5.1
|
invoke>=0.5.1
|
||||||
invocations>=0.4.0
|
invocations>=0.4.0
|
||||||
|
# Tests
|
||||||
spec>=0.11.1
|
spec>=0.11.1
|
||||||
|
# Docs
|
||||||
|
-e .
|
||||||
sphinx>=1.1
|
sphinx>=1.1
|
||||||
|
sphinx_rtd_theme>=0.1.5
|
||||||
|
|
|
||||||
37
docs/changelog.rst
Normal file
37
docs/changelog.rst
Normal file
|
|
@ -0,0 +1,37 @@
|
||||||
|
=========
|
||||||
|
Changelog
|
||||||
|
=========
|
||||||
|
|
||||||
|
* :release:`0.3.0 <2013-11-06>`
|
||||||
|
* :feature:`1` (also :issue:`3`, :issue:`10`) Allow using ``0`` as a dummy
|
||||||
|
issue number, which will result in no issue number/link being displayed.
|
||||||
|
Thanks to Markus Zapke-Gründemann and Hynek Schlawack for patches &
|
||||||
|
discussion.
|
||||||
|
|
||||||
|
* This feature lets you categorize changes that aren't directly related
|
||||||
|
to issues in your tracker. It's an improvement over, and replacement
|
||||||
|
for, the previous "vanilla bullet list items are treated as bugs"
|
||||||
|
behavior.
|
||||||
|
* Said behavior (non-role-prefixed bullet list items turning into
|
||||||
|
regular bugs) is being retained as there's not a lot to gain from
|
||||||
|
deactivating it.
|
||||||
|
|
||||||
|
* :release:`0.2.4 <2013.10.04>`
|
||||||
|
* :support:`0 backported` Handful of typos, doc tweaks & addition of a
|
||||||
|
.gitignore file. Thanks to Markus Zapke-Gründemann.
|
||||||
|
* :bug:`0` Fix duplicate display of "bare" (not prefixed with an issue role)
|
||||||
|
changelog entries. Thanks again to Markus.
|
||||||
|
* :support:`0 backported` Edited the README/docs to be clearer about how
|
||||||
|
Releases works/operates.
|
||||||
|
* :support:`0 backported` Explicitly documented how non-role-prefixed line
|
||||||
|
items are preserved.
|
||||||
|
* :bug:`0` Updated non-role-prefixed line items so they get prefixed with a
|
||||||
|
'[Bug]' signifier (since they are otherwise treated as bugfix items.)
|
||||||
|
* :release:`0.2.3 <2013.09.16>`
|
||||||
|
* :bug:`0` Fix a handful of bugs in release assignment logic.
|
||||||
|
* :release:`0.2.2 <2013.09.15>`
|
||||||
|
* :bug:`0` Ensured Python 3 compatibility.
|
||||||
|
* :release:`0.2.1 <2013.09.15>`
|
||||||
|
* :bug:`0` Fixed a stupid bug causing invalid issue hyperlinks.
|
||||||
|
* :release:`0.2.0 <2013.09.15>`
|
||||||
|
* :feature:`0` Basic functionality.
|
||||||
29
docs/conf.py
Normal file
29
docs/conf.py
Normal file
|
|
@ -0,0 +1,29 @@
|
||||||
|
from datetime import datetime
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
|
||||||
|
import sphinx_rtd_theme
|
||||||
|
|
||||||
|
|
||||||
|
extensions = []
|
||||||
|
templates_path = ['_templates']
|
||||||
|
source_suffix = '.rst'
|
||||||
|
master_doc = 'index'
|
||||||
|
|
||||||
|
project = u'Releases'
|
||||||
|
year = datetime.now().year
|
||||||
|
copyright = u'%d Jeff Forcier' % year
|
||||||
|
|
||||||
|
# Ensure project directory is on PYTHONPATH for version, autodoc access
|
||||||
|
sys.path.insert(0, os.path.abspath(os.path.join(os.getcwd(), '..')))
|
||||||
|
|
||||||
|
exclude_patterns = ['_build']
|
||||||
|
|
||||||
|
# RTD theme
|
||||||
|
html_theme = "sphinx_rtd_theme"
|
||||||
|
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||||
|
|
||||||
|
# Dogfood
|
||||||
|
extensions.append('releases')
|
||||||
|
releases_release_uri = "https://github.com/bitprophet/releases/tree/%s"
|
||||||
|
releases_issue_uri = "https://github.com/bitprophet/releases/issues/%s"
|
||||||
13
docs/index.rst
Normal file
13
docs/index.rst
Normal file
|
|
@ -0,0 +1,13 @@
|
||||||
|
========
|
||||||
|
Releases
|
||||||
|
========
|
||||||
|
|
||||||
|
.. include:: ../README.rst
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
usage
|
||||||
|
changelog
|
||||||
|
todo
|
||||||
12
docs/todo.rst
Normal file
12
docs/todo.rst
Normal file
|
|
@ -0,0 +1,12 @@
|
||||||
|
====
|
||||||
|
TODO
|
||||||
|
====
|
||||||
|
|
||||||
|
* Tests would be nice.
|
||||||
|
* Possibly add more keywords to allow control over additional edge cases.
|
||||||
|
* Add shortcut format option for the release/issue URI settings - GitHub users
|
||||||
|
can just give their GitHub acct/repo and we will fill in the rest.
|
||||||
|
* Maybe say pre-1.0 releases consider all bugs 'major' (so one can e.g. put out
|
||||||
|
an 0.4.0 which is all bugfixes). Iffy because what if you *wanted* regular
|
||||||
|
feature-vs-bugfix releases pre-1.0? (which is common.)
|
||||||
|
* Make sure regular ``:issue:`` is documented.
|
||||||
68
docs/usage.rst
Normal file
68
docs/usage.rst
Normal file
|
|
@ -0,0 +1,68 @@
|
||||||
|
=====
|
||||||
|
Usage
|
||||||
|
=====
|
||||||
|
|
||||||
|
To use Releases, mimic the format seen in `its own changelog
|
||||||
|
<https://raw.github.com/bitprophet/releases/master/docs/changelog.rst>`_ or in
|
||||||
|
`Fabric's changelog
|
||||||
|
<https://raw.github.com/fabric/fabric/master/docs/changelog.rst>`_.
|
||||||
|
Specifically:
|
||||||
|
|
||||||
|
* Install ``releases`` and update your Sphinx ``conf.py`` to include it in the
|
||||||
|
``extensions`` list setting: ``extensions = ['releases']``.
|
||||||
|
|
||||||
|
* Also set the ``releases_release_uri`` and ``releases_issue_uri`` top
|
||||||
|
level options - they determine the targets of the issue & release links
|
||||||
|
in the HTML output. Both should have an unevaluated ``%s`` where the
|
||||||
|
release/issue number would go.
|
||||||
|
* See `Fabric's docs/conf.py
|
||||||
|
<https://github.com/fabric/fabric/blob/4afd33e971f1c6831cc33fd3228013f7484fbe35/docs/conf.py#L31>`_
|
||||||
|
for an example.
|
||||||
|
|
||||||
|
* Create a Sphinx document named ``changelog.rst`` with a top-level header
|
||||||
|
followed by a bulleted list.
|
||||||
|
* List items are to be ordered chronologically with the newest ones on top.
|
||||||
|
|
||||||
|
* As you fix issues, put them on the top of the list.
|
||||||
|
* As you cut releases, put those on the top of the list and they will
|
||||||
|
include the issues below them.
|
||||||
|
* Issues with no releases above them will end up in a specially marked
|
||||||
|
"Unreleased" section of the rendered changelog.
|
||||||
|
|
||||||
|
* Bullet list items should use the ``support``, ``feature`` or ``bug``
|
||||||
|
roles to mark issues, or ``release`` to mark a release. These special roles
|
||||||
|
must be the first element in each list item.
|
||||||
|
|
||||||
|
* Line-items that do not start with any issue role will be considered bugs
|
||||||
|
(both in terms of inclusion in releases, and formatting) and, naturally,
|
||||||
|
will not be given a hyperlink.
|
||||||
|
|
||||||
|
* Issue roles are of the form ``:type:`number[ keyword]```. Specifically:
|
||||||
|
|
||||||
|
* ``number`` is used to generate the link to the actual issue in your issue
|
||||||
|
tracker (going by the ``releases_issue_uri`` option). It's used for both
|
||||||
|
the link target & (part of) the link text.
|
||||||
|
* If ``number`` is ``0`` no issue link will be generated. You can use this
|
||||||
|
for items without a related issue.
|
||||||
|
* Keywords are optional and may be one of:
|
||||||
|
|
||||||
|
* ``backported``: Given on *support* or *feature* issues to denote
|
||||||
|
backporting to bugfix releases; such issues will show up in both
|
||||||
|
release types. E.g. placing ``:support:`123 backported``` in your
|
||||||
|
changelog below releases '1.1.1' and '1.2.0' will cause it to appear
|
||||||
|
in both of those releases' lists.
|
||||||
|
* ``major``: Given on bug issues to denote inclusion in feature,
|
||||||
|
instead of bugfix, releases. E.g. placing ``:bug:`22 major``` below
|
||||||
|
releases '1.1.1' and '1.2.0' will cause it to appear in '1.2.0'
|
||||||
|
**only**.
|
||||||
|
|
||||||
|
* Regular Sphinx content may be given after issue roles and will be preserved
|
||||||
|
as-is when rendering. For example, in ``:bug:`123` Fixed a bug, thanks
|
||||||
|
`@somebody`!``, the rendered changelog will preserve/render "Fixed a bug,
|
||||||
|
thanks ``@somebody``!" after the issue link.
|
||||||
|
* Release roles are of the form ``:release:`number <date>```. Do not place any
|
||||||
|
additional content after release roles - it will be ignored.
|
||||||
|
|
||||||
|
Then build your docs; in the rendered output, ``changelog.html`` should show
|
||||||
|
issues grouped by release, as per the above rules. Example: `Fabric's rendered
|
||||||
|
changelog <http://docs.fabfile.org/en/latest/changelog.html>`_.
|
||||||
Loading…
Add table
Reference in a new issue