A powerful Sphinx changelog-generating extension.

Hi despite having releases in the extensions list of my docs/source.conf.py I get the following error:

pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 31%] changes                                                                                                                                
Exception occurred:
  File "/home/prologic/.virtualenvs/circuits/lib/python2.7/site-packages/sphinx/writers/html.py", line 588, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: issue
The full traceback has been saved in /tmp/sphinx-err-8G5mEk.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make: *** [html] Error 1

Fatal error: local() encountered an error (return code 2) while executing 'make html'

Aborting.

I.e. right now, in Paramiko, going from 1.x to 2.x results in: surprise! there's no 2.x displayed anywhere!

Clearly the parse and/or organization logic breaks down in some way, which isn't too surprising, I'm sure there's a lot of assumptions baked in aimed squarely at iterating over minor releases only.

Fixing this may end up solving (fully or partly) #19 and #36.

Remaining todo

• [x] Figure out whether we have solved #19 / #36 or not
• [x] Address whether advanced spec format should imply major/backported behavior or not
• [ ] Implement config option re: issues 'sticking' to latest major release family by default

https://github.com/bitprophet/releases/compare/1.3.1...master

f5fcad3 didn't make it in

tmuxp-qUA_BCEU ❯ pipenv graph
aafigure==0.6
alagitpull==0.0.13
  - alabaster [required: ==0.7.10, installed: 0.7.10]
pytest-rerunfailures==3.1
  - pytest [required: >=2.7.3, installed: 3.2.3]
    - py [required: >=1.4.33, installed: 1.4.34]
    - setuptools [required: Any, installed: 36.6.0]
releases==1.3.1
  - semantic-version [required: <3.0, installed: 2.6.0]
  - sphinx [required: <1.5,>=1.3, installed: 1.6.4]
    - alabaster [required: >=0.7,<0.8, installed: 0.7.10]
    - babel [required: !=2.0,>=1.3, installed: 2.5.1]
      - pytz [required: >=0a, installed: 2017.2]
    - docutils [required: >=0.11, installed: 0.14]
    - imagesize [required: Any, installed: 0.7.1]
    - Jinja2 [required: >=2.3, installed: 2.9.6]
      - MarkupSafe [required: >=0.23, installed: 1.0]
    - Pygments [required: >=2.0, installed: 2.2.0]
    - requests [required: >=2.0.0, installed: 2.18.4]
      - certifi [required: >=2017.4.17, installed: 2017.7.27.1]
      - chardet [required: <3.1.0,>=3.0.2, installed: 3.0.4]
      - idna [required: >=2.5,<2.7, installed: 2.6]
      - urllib3 [required: <1.23,>=1.21.1, installed: 1.22]
    - setuptools [required: Any, installed: 36.6.0]
    - six [required: >=1.5, installed: 1.11.0]
    - snowballstemmer [required: >=1.1, installed: 1.2.1]
    - sphinxcontrib-websupport [required: Any, installed: 1.0.1]
tmuxp==1.3.4
  - click [required: ==6.7, installed: 6.7]
  - colorama [required: ==0.3.9, installed: 0.3.9]
  - kaptan [required: >=0.5.7, installed: 0.5.8]
    - PyYAML [required: Any, installed: 3.12]
  - libtmux [required: ==0.7.5, installed: 0.7.5]

Using releases 0.6.1 and most earlier versions, I get the same exception as in #22 and #24. Here is the Sphinx error log :

# Sphinx version: 1.2.2
# Python version: 2.7.6
# Docutils version: 0.11 release
# Jinja2 version: 2.7.2
# Loaded extensions:
#   sphinx.ext.todo from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/ext/todo.pyc
#   sphinxcontrib.programoutput from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinxcontrib/programoutput.pyc
#   releases from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/releases/__init__.pyc
#   sphinx.ext.intersphinx from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/ext/intersphinx.pyc
#   sphinx.ext.oldcmarkup from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/ext/oldcmarkup.pyc
Traceback (most recent call last):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/cmdline.py", line 254, in main
    app.build(force_all, filenames)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/application.py", line 212, in build
    self.builder.build_update()
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 214, in build_update
    'out of date' % len(to_build))
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 276, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 320, in write
    self._write_serial(sorted(docnames), warnings)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 333, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/html.py", line 433, in write_doc
    self.docwriter.write(doctree, destination)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/writers/html.py", line 51, in translate
    self.document.walkabout(visitor)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 1882, in dispatch_visit
    return method(node)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/writers/html.py", line 588, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: issue

Since this changelog.rst does not belong to an opensource project, I'll send it to you by e-mail.

I tried many versions of release; and the 0.2.4 version builds this changelog.rst file successfully. More recent ones do not.

Thanks for your help !

Sort of a follow-on from #71, which prompted me to dig deeper into how we were not really compatible with Sphinx 1.5/1.6.

Sphinx 1.5 was just due to Python 2.6 being dropped, so we did that here too, and no problem.

Sphinx 1.6 made a lot of internal API changes that broke us. I fixed all the stuff that seems to pop up in our test suites, but there's a side channel - parsing the changelog 'in-process' for stuff like my release Invoke tasks (which need to answer questions about a project's changelog state.)

Specifically, something seems to be almost skipping Sphinx itself when rendering, leaving us with "I'm docutils and what is this???" errors like:

Well...clearly :doc: should freaking work in Sphinx-flavored RST! (It also complained about a :ref: that I temporarily commented out.)

I have enjoyed using releases on several projects and am looking to use it on several more.

I am wondering if it is possible to process multiple "changelog" files?

The particular situation I have is that I have several small projects around a common theme. I would like to maintain a changelog per project, but would like to maintain only one documentation site for the lot of them. Suggestions on how to do this?

Friend of the project @sivy tried to use it for a wholly-unreleased changelog (i.e. no :release: directives whatsoever) and ran into what is probably just an assumption-related bug. See https://gist.github.com/sivy/2cf88b595722ffcb7163 for details. Offhand we should be able to cope with this (the parsing step should end with just the 'unreleased' release object holding all issues, and render as such).

Problem

• Young projects with just a master branch & rapid iteration (like...this project) are often tempted to slam out arbitrary feature releases ("ehhh let's call this 0.3.0"), sometimes with bugfix releases in between, sometimes not - but almost always w/o really keeping release lines, numbers just go up.
• In this setup, the distinction between feature and bugfix releases can be blurred or nonexistent.
• That clashes with how Releases thinks about the world (namely, from a mature-project, multiple-release-line perspective.) Young projects must constantly remember to mark bugs as 'major', at the very least.

Solutions

1. Education only: document the phenomenon of pre-1.0 single-line release setups, remind that "mixed" releases will need to mark up the bugs and/or features as appropriate so they show up right.
2. Logic update: pre-1.0 releases are considered to consume all issues listed since previous release. Maybe make this configurable for users who don't want it.
   • Counterpoint: this could confuse users since the behavior changes post 1.0, possibly "without warning."
3. Do both: document it, make an opt-in (not opt-out) option saying "yes I want lazy pre-1.0 releases that suck up all issues".

Last feels best.

Or something. See e.g. invocations exploding when it attempts to import Releases 1.4.0 on travis recently (with no changes on my end on either project):

Traceback (most recent call last):
  File "/home/travis/virtualenv/python2.7.14/bin/inv", line 11, in <module>
    sys.exit(program.run())
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/invoke/program.py", line 282, in run
    self.parse_collection()
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/invoke/program.py", line 356, in parse_collection
    self.load_collection()
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/invoke/program.py", line 508, in load_collection
    module, parent = loader.load(coll_name)
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/invoke/loader.py", line 69, in load
    module = imp.load_module(name, fd, path, desc)
  File "/home/travis/build/pyinvoke/invocations/tasks.py", line 3, in <module>
    from invocations.packaging import release
  File "/home/travis/build/pyinvoke/invocations/invocations/packaging/__init__.py", line 3, in <module>
    from . import release
  File "/home/travis/build/pyinvoke/invocations/invocations/packaging/release.py", line 30, in <module>
    from releases.util import parse_changelog
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/releases/util.py", line 15, in <module>
    from sphinx.environment import (
ImportError: cannot import name SphinxStandaloneReader

(link: https://travis-ci.org/pyinvoke/invocations/jobs/357642688#L573-L593)

Kinda frustrating since it's not like that particular class is marked as being private or anything, but, such is Sphinx.

Need to either dial back Releases' setup.py (which I'm not a fan of but given Sphinx has broken us two minor releases in a row, seems prudent...) or dive in and add more conditional imports and such.

If you:

• clone github.com/pypa/twine,
• update tox.ini to allow 1.6.1, and
• run tox -e docs you'll reproduce it. The logs from sphinx are here:

# Sphinx version: 1.6.1
# Python version: 2.7.13 (CPython)
# Docutils version: 0.13.1 release
# Jinja2 version: 2.9.6
# Last messages:
#   making output directory...
#   loading pickled environment...
#   not yet created
#   loading intersphinx inventory from http://docs.python.org/objects.inv...
#   intersphinx inventory has moved: http://docs.python.org/objects.inv -> https://docs.python.org/2/objects.inv
#   building [mo]: targets for 0 po files that are out of date
#   building [html]: targets for 2 source files that are out of date
#   updating environment:
#   2 added, 0 changed, 0 removed
#   reading sources... [ 50%] changelog
# Loaded extensions:
#   releases (unknown version) from /home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/releases/__init__.pyc
#   sphinx.ext.coverage (1.6.1) from /home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/ext/coverage.pyc
#   alabaster (0.7.10) from /home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/alabaster/__init__.pyc
#   sphinx.ext.autodoc (1.6.1) from /home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/ext/autodoc.pyc
#   sphinx.ext.doctest (1.6.1) from /home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/ext/doctest.pyc
#   sphinx.ext.viewcode (1.6.1) from /home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/ext/viewcode.pyc
#   sphinx.ext.intersphinx (1.6.1) from /home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/ext/intersphinx.pyc
Traceback (most recent call last):
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/cmdline.py", line 306, in main
    app.build(opts.force_all, filenames)
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/application.py", line 338, in build
    self.builder.build_update()
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 328, in build_update
    'out of date' % len(to_build))
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 341, in build
    updated_docnames = set(self.env.update(self.config, self.srcdir, self.doctreedir))
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/environment/__init__.py", line 584, in update
    self._read_serial(docnames, self.app)
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/environment/__init__.py", line 603, in _read_serial
    self.read_doc(docname, app)
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/sphinx/environment/__init__.py", line 718, in read_doc
    pub.publish()
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/docutils/core.py", line 218, in publish
    self.apply_transforms()
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/docutils/core.py", line 199, in apply_transforms
    self.document.transformer.apply_transforms()
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/docutils/transforms/__init__.py", line 171, in apply_transforms
    transform.apply(**kwargs)
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/docutils/transforms/universal.py", line 294, in apply
    txtnode.parent.replace(txtnode, nodes.Text(newtext))
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/docutils/nodes.py", line 928, in replace
    index = self.index(old)
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/docutils/nodes.py", line 689, in index
    return self.children.index(item)
  File "/home/sigmavirus24/sandbox/pypa/twine/.tox/docs/lib/python2.7/site-packages/releases/models.py", line 62, in __eq__
    if getattr(self, attr) != getattr(other, attr):
AttributeError: 'Text' object has no attribute 'type'

I'll take a look into fixing this later, but I don't have the time right this second. :)

If I only use the "-" or "0" options in my project, and don't configure the releases_issue_uri and releases_release_uri options in my conf.py file, I get the following stack trace:

Exception occurred:
  File "...\.tox\docs\lib\site-packages\releases\__init__.py", line 129, in release_nodes
    link = '<a class="reference external" href="{0}">{1}</a>'.format(uri, text)
UnboundLocalError: local variable 'uri' referenced before assignment

This is not super user friendly. If the options are required (looks like it from the docs), shouldn't we try to enforce the presence?

Also, since it's possible not to use these at all, can we make it optional? I understand that if someone uses the issue numbers but doesn't set the options, then maybe we'd want a warning or something, but crashing like this is probably not what you had in mind.

I'm willing to send in a patch if you're interested. Just let me know what you want as the final behavior.

Just found that I'm not able to generate man page in sphinx-theme-alabaster python module (https://github.com/bitprophet/alabaster/)

+ sphinx-build -b man -d sphinx-theme-alabaster docs .
Running Sphinx v3.5.3
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [ 25%] changelog
Extension error (releases):
Handler <function generate_changelog at 0x7f85d9b5eee0> for event 'doctree-read' threw an exception (exception: Call either Version('1.2.3') or Version(major=1, ...).)

A while ago semantic-version was pinned to <2.7. This is now starting to cause problems as other packages are moving to require newer versions (in our case py-solc-x which requires semantic_version>=2.8.1,<3).

I see that there's #86 (and the reworked branch based on that). Would it help for someone else to pick that up, or do you already know what needs to be done?

Over at pygae/galgebra, a lot of my release notes are of the form The function :func:useless_functionwas deprecated. Since these are neither features nor bugfixes, we're currently categorizing them as :support:.

Would it be possible to introduce some more categories? Specifically, I'm finding myself wanting:

• :deprecation:, for functions which have been changed to emit a warning upon use.
• :removal:, for features which have been removed (typically those marked with :deprecation: in a previous release).

Reasoning behind the request

Hello!

So I have a feature request which may sound strange to you as it does not 100% follow the semantic versioning ethos. But there are projects like mine which like things simple. I want all issues under a release to be put as part of that release when rendered.

So essentially what unstable-prehistory-mode does, except I want it to also carry on after v1.0. I know I can start specifying which issue belongs to each release, but at that point I am fighting the tool instead of using it.

Why you may ask? For our project:

• Each minor release after v1.0 is feature heavy (and perhaps some bugs).
• Each patch release is mostly quick hotfixes for stuff that break a previous minor release.
• And we are a bit reluctant to use the major version number. So no v2.0 soon.

With the above characteristics the default way the tool operates does not really work.

Feature request specification

Add a new switch that essentially does not stop the unstable-prehistory-mode after v1.0.

I really like what releases has done, and I'm considering adopting it in place of the technique I've ~~developed~~cobbled together, which performs textual substitution on the .rst to inject links.

One feature I'd miss dearly in a transition to releases, however, is the date inference. Rst.linker will inject a timestamp based on SCM metadata (the date the tag was created). This approach allows a maintainer to simply publish the release version, but get release dates reflected in the published docs.

Perhaps releases could offer this behavior as an opt-in feature, maybe by default if no <date> is supplied in the release directive.

the follow error is raising here:

Warning, treated as error:
the releases extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit

does anyone know how to fix that?