additional lists in changelog break Sphinx

[MinchinWeb]

Today I discovered that if you have list above your changelog, Sphinx will choke on it. This is also true if the pre-changelog list is in an included file. Example (broken) changelog:

Changes
=======

- list
- items

more text

- :release:`0.1.0 <2017-02-07>`
- :bug:`1` nothing yet

If nothing else, it would be helpful to provide some sort of useful error message, rather than just crashing Sphinx. This is the error currently shown:

Exception occurred:
  File "c:\program files\python36\lib\site-packages\sphinx\writers\html.py", lin
e 722, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: Release

[bitprophet]

Yea right now the expected "API" for the plugin is "I expect your changelog to have a single, changeloggy list in it". (Originally we didn't account for eg paragraphs above the list either, but that's been fixed awhile.)

Open to suggestions on how best to signal which of multiple lists is the one to grab; been a bit since I looked at that part of the code but perhaps we can change the logic to "first list that appears to have our Release/Issue node types within it"...

---

Re: the error, there's not much we can do on our end because the core problem is that we have to passively hook into Sphinx's event pipeline and wait for it to find and execute on our changelog; so if something like this happens and our custom node types are never found/processed, they foul up the regular Sphinx rendering step.

(It's possible we could identify what that step would do to our nodes and implement the appropriate methods, which then raise a more useful exception...?)

[MinchinWeb]

Two thoughts:

• in determining which list to use, maybe make it explicit by using a ReST directive. Potentially, this would allow you to have multiple changelogs within the Spinx generation (c.f. #59), and even within the same document. This would be a breaking change, and so should be part of the 2.0.0 release. In this case, you changelog would look like:

  Changes
  =======
  
  - list
  - items
  
  more text
  
  changelog::
  
      - :release:`0.1.0 <2017-02-07>`
      - :bug:`1` nothing yet

• in dealing with errors related to release node being undefined outside of a changelog list, would is be possible (simple?) to have the node function as a "pass-through" node, where the text would get passed through unchanged to the final document, which a warning is printed to the console? This is, in effect, how the nodes are treated is releases isn't installed.