hiro/releases
1
0
Fork 0
mirror of https://github.com/vale981/releases synced 2025-03-04 09:11:41 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

1st stab at real Sphinx docs hurr

Browse source
This commit is contained in:
Jeff Forcier 2013-11-11 07:45:41 -08:00
parent 5d0717b7de
commit 053d372fbb
8 changed files with 175 additions and 129 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -2,3 +2,4 @@
*.egg*
.*.swp
build/
docs/_build

139
README.rst
View file

@ -1,9 +1,8 @@
=================================
Releases, a Sphinx changelog tool
=================================
.. image:: https://secure.travis-ci.org/bitprophet/releases.png?branch=master
:target: https://travis-ci.org/bitprophet/releases
About
=====
What is Releases?
=================
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
@ -24,128 +23,10 @@ Specifically:
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/>`_.
Usage
=====
For more documentation, including detailed installation and usage information,
please see http://releases.readthedocs.org.
Mimic the format seen `in Fabric's changelog
<https://raw.github.com/fabric/fabric/master/docs/changelog.rst>`_:
* 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>`_.
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.)
.. note::
You can install the `development version
<https://github.com/bitprophet/releases/tarball/master#egg=releases-dev>`_
via ``pip install releases==dev``.

5
dev-requirements.txt
View file

@ -1,4 +1,9 @@
# Task runner
invoke>=0.5.1
invocations>=0.4.0
# Tests
spec>=0.11.1
# Docs
-e .
sphinx>=1.1
sphinx_rtd_theme>=0.1.5

37
docs/changelog.rst Normal file
View 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
View 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
View file

@ -0,0 +1,13 @@
========
Releases
========
.. include:: ../README.rst
.. toctree::
:maxdepth: 2
usage
changelog
todo

12
docs/todo.rst Normal file
View 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
View 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>`_.