Merge pull request #37 from Holzhaus/documentation-fixes

Documentation Fixes

.pre-commit/version_check.py

@@ -12,7 +12,7 @@ import docutils.parsers.rst
 import docutils.utils
 import docutils.frontend
 
-CHANGELOG_PATTERN = re.compile(r"^Version (\S+)((?: \(unreleased\)))?$")
+CHANGELOG_PATTERN = re.compile(r"^Version (\S+)((?: \(.+\)))?$")
 
 
 def parse_rst(text: str) -> docutils.nodes.document:
@@ -56,15 +56,15 @@ def get_sphinxchangelog_version(rootdir):
     matchobj = CHANGELOG_PATTERN.match(visitor.sectiontitles_found[1])
     assert matchobj
     version = matchobj.group(1)
-    version_unreleased = matchobj.group(2)
+    version_date = matchobj.group(2)
 
     matchobj = CHANGELOG_PATTERN.match(visitor.sectiontitles_found[2])
     assert matchobj
     release = matchobj.group(1)
-    release_unreleased = matchobj.group(2)
+    release_date = matchobj.group(2)
 
-    if version_unreleased:
-        assert release_unreleased
+    if version_date:
+        assert version_date == release_date
 
     return version, release
 

docs/changelog.rst

@@ -19,28 +19,28 @@ Version 0.2.4 (unreleased)
 * Rewrite the path handling of the Sphinx extension to handle branch names containing a forward slash properly on Windows and add unittests and Windows CI builds to make sure it doesn't break on future updates. (`#31 <issue31_>`_, `#35 <issue35_>`_)
 
 
-Version 0.2.3
--------------
+Version 0.2.3 (2020-05-04)
+--------------------------
 
 * Fixed return codes of main() function and exit with non-zero status if no matching refs were found.
 * Added some logging calls to the git module.
 * Fixed bug where local branch was used to check the existence of files on remote branches.
 
 
-Version 0.2.2
--------------
+Version 0.2.2 (2020-05-01)
+--------------------------
 
 * Added additional checks to determine if a branch or tag contains both the Sphinx source directory and the :file:`conf.py` file. If that's not the case, that branch or tag is skipped automatically and not copied to the temporary directory. (`#9 <issue9_>`_)
 
 
-Version 0.2.1
--------------
+Version 0.2.1 (2020-04-19)
+--------------------------
 
 * Fixed handling of absolute output paths in `vpathto` and ensure that all generated paths are relative.
 
 
-Version 0.2.0
--------------
+Version 0.2.0 (2020-04-19)
+--------------------------
 
 * Added a way to override config variables using placeholders that expand to each version's actual value (`#4 <issue4_>`_, `#7 <issue7_>`_).
 
@@ -48,14 +48,14 @@ Version 0.2.0
 Version 0.1
 ===========
 
-Version 0.1.1
--------------
+Version 0.1.1 (2020-03-12)
+--------------------------
 
 * Fixed version number in documentation
 * Fixed issue that caused the wrong configuration directory being used when the ``-c`` argument was not specified on the command line
 
-Version 0.1.0
--------------
+Version 0.1.0 (2020-03-11)
+--------------------------
 
 * Initial release
 

docs/faq.rst

@@ -24,10 +24,16 @@ Then it copies the data for each version into separate temporary directories, bu
 The :file:`conf.py` file from the currently checked out branch will be used to build old versions, so it's not necessary to make changes old branches or tags to add support for ``sphinx-multiversion``.
 This also means that theme improvements, template changes, etc. will automatically be applied to old versions without needing to add commits.
 
+
 Do I need to make changes to old branches or tags?
 ==================================================
 
-No, you don't. ``sphinx-multiversion`` will always use the :file:`conf.py` file from you currently checked out branch.
+No, you don't. ``sphinx-multiversion`` will always use the :file:`conf.py` file from your currently checked out branch.
+
+The downside is that this behaviour restricts the kinds of changes you may do to your configuration, because it needs to retain compatibility with old branches.
+For example, if your :file:`conf.py` file hardcodes a path (e.g. for opening a file), but that file does not exist in some older branches that you want to build documentation for, this will cause issues.
+In these cases you will need to add a check if a file actually exists and adapt the path accordingly.
+
 
 What are the license terms of ``sphinx-multiversion``?
 ======================================================