Allow multiple changelog files

Includes documentation updates;
Fixes #59

docs/changelog.rst

@@ -2,6 +2,8 @@
 Changelog
 =========
 
+* :feature:`59` Allow multiple changelog files. Thanks to William Minchin for
+  the patch.
 * :release:`1.2.1 <2016-07-25>`
 * :support:`51 backported` Modernize release management so PyPI trove
   classifiers are more accurate, wheel archives are universal instead of Python

docs/usage.rst

@@ -48,6 +48,12 @@ Specifically:
       (as per previous bullet point), ``releases_document_name``. E.g.
       ``releases_document_name = "CHANGES"`` would cause Releases to mutate a
       file called ``CHANGES.rst`` instead of ``changelog.rst``.
+    * It is possible to have multiple changelogs (useful, for example, if you
+      are documenting multiple sub-projects). In this case set
+      ``releases_docuement_name`` to a list containing all the changelogs you
+      want processed. Each changelog must be explicitly listed. E.g.
+      ``releases_document_name = ['project_1/changelog', 'project_2/changes',
+      'changelog']``
     * Elements before or after this bulleted list will be untouched by
       Releases, allowing you to place e.g. paragraphs, comments etc at the top
       (or bottom) of the document.

releases/__init__.py

@@ -598,8 +598,8 @@ class BulletListVisitor(nodes.NodeVisitor):
 
 def generate_changelog(app, doctree):
     # Don't scan/mutate documents that don't match the configured document name
-    # (which by default is changelog.rst).
-    if app.env.docname != app.config.releases_document_name:
+    # (which by default is ['changelog.rst', ]).
+    if app.env.docname not in app.config.releases_document_name:
         return
 
     # Find the first bullet-list node & replace it with our organized/parsed
@@ -619,7 +619,7 @@ def setup(app):
         # Convenience Github version of above
         ('github_path', None),
         # Which document to use as the changelog
-        ('document_name', 'changelog'),
+        ('document_name', ['changelog', ]),
         # Debug output
         ('debug', False),
         # Whether to enable linear history during 0.x release timeline
@@ -629,6 +629,12 @@ def setup(app):
         app.add_config_value(
             name='releases_{0}'.format(key), default=default, rebuild='html'
         )
+    # if a string is given for `document_name`, convert it to a list
+    # done to maintain backwards compatibility
+    if isinstance(app.config.releases_document_name, str):
+        app.config.releases_document_name = \
+            [app.config.releases_document_name, ]
+
     # Register intermediate roles
     for x in list(ISSUE_TYPES) + ['issue']:
         app.add_role(x, issues_role)