From 053d372fbbfc15f7f261454f03fcdec0e3af881d Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 11 Nov 2013 07:45:41 -0800 Subject: [PATCH] 1st stab at real Sphinx docs hurr --- .gitignore | 1 + README.rst | 139 ++++--------------------------------------- dev-requirements.txt | 5 ++ docs/changelog.rst | 37 ++++++++++++ docs/conf.py | 29 +++++++++ docs/index.rst | 13 ++++ docs/todo.rst | 12 ++++ docs/usage.rst | 68 +++++++++++++++++++++ 8 files changed, 175 insertions(+), 129 deletions(-) create mode 100644 docs/changelog.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/todo.rst create mode 100644 docs/usage.rst diff --git a/.gitignore b/.gitignore index eb1f639..93cd593 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ *.egg* .*.swp build/ +docs/_build diff --git a/README.rst b/README.rst index 668dc9a..6e79e84 100644 --- a/README.rst +++ b/README.rst @@ -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 `_ 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 `_. -Usage -===== +For more documentation, including detailed installation and usage information, +please see http://releases.readthedocs.org. -Mimic the format seen `in Fabric's changelog -`_: - -* 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 - `_ - 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 ```. 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 `_. - -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 + `_ + via ``pip install releases==dev``. diff --git a/dev-requirements.txt b/dev-requirements.txt index 2388c2c..8df8fae 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -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 diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..6dde34b --- /dev/null +++ b/docs/changelog.rst @@ -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. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..cc71a8d --- /dev/null +++ b/docs/conf.py @@ -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" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..dfdb261 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,13 @@ +======== +Releases +======== + +.. include:: ../README.rst + + +.. toctree:: + :maxdepth: 2 + + usage + changelog + todo diff --git a/docs/todo.rst b/docs/todo.rst new file mode 100644 index 0000000..440b949 --- /dev/null +++ b/docs/todo.rst @@ -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. diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..1bdc30c --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,68 @@ +===== +Usage +===== + +To use Releases, mimic the format seen in `its own changelog +`_ or in +`Fabric's changelog +`_. +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 + `_ + 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 ```. 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 `_.