docs: update and add changelog

Author: paulmueller

CHANGELOG

@@ -3,6 +3,7 @@
  - setup: migrate to GitHub Actions
  - setup: migrate to pyproject.toml
  - docs: remove dependency on old mock standalone library (#19)
+ - docs: overhaul and add changelog
 0.3.3
  - fix: add constant `ZERO_CUTOFF` that defines when a trace average is
    treated as zero

docs/conf.py

@@ -74,6 +74,7 @@
               'sphinx.ext.viewcode',
               'sphinx.ext.napoleon',
               'fancy_include',
+              'github_changelog',
               ]
 
 
@@ -143,7 +144,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/extensions/github_changelog.py

@@ -0,0 +1,75 @@
+"""Display changelog with links to GitHub issues
+
+Usage
+-----
+The directive
+
+   .. include_changelog:: ../CHANGELOG
+
+adds the content of the changelog file into the current document.
+References to GitHub issues are identified as "(#XY)" (with parentheses
+and hash) and a link is inserted
+
+ https://github.com/RI-imaging/{PROJECT}/issues/{XY}
+
+where PROJECT ist the `project` variable defined in conf.py.
+"""
+import io
+import re
+
+from docutils.statemachine import ViewList
+from docutils.parsers.rst import Directive
+from sphinx.util.nodes import nested_parse_with_titles
+from docutils import nodes
+
+
+class IncludeDirective(Directive):
+    required_arguments = 1
+    optional_arguments = 0
+
+    def run(self):
+        full_path = self.arguments[0]
+        project = self.state.document.settings.env.config.github_project
+
+        def insert_github_link(reobj):
+            line = reobj.string
+            instr = line[reobj.start():reobj.end()]
+            issue = instr.strip("#()")
+            link = "https://github.com/{}/issues/".format(project)
+            rstlink = "(`#{issue} <{link}{issue}>`_)".format(issue=issue,
+                                                             link=link)
+            return rstlink
+
+        with io.open(full_path, "r") as myfile:
+            text = myfile.readlines()
+
+        rst = []
+        for line in text:
+            line = line.strip("\n")
+            if line.startswith("  ") and line.strip().startswith("-"):
+                # list in list:
+                rst.append("")
+            if not line.startswith(" "):
+                rst.append("")
+                line = "version " + line
+                rst.append(line)
+                rst.append("-"*len(line))
+            elif not line.strip():
+                rst.append(line)
+            else:
+                line = re.sub(r"\(#[0-9]*\)", insert_github_link, line)
+                rst.append(line)
+
+        vl = ViewList(rst, "fakefile.rst")
+        # Create a node.
+        node = nodes.section()
+        node.document = self.state.document
+        # Parse the rst.
+        nested_parse_with_titles(self.state, vl, node)
+        return node.children
+
+
+def setup(app):
+    app.add_config_value('github_project', "user/project", 'html')
+    app.add_directive('include_changelog', IncludeDirective)
+    return {'version': '0.1'}   # identifies the version of our extension

docs/index.rst

@@ -17,24 +17,46 @@ Summary:
     correlate_numpy
 
 
+.. _sec_ac:
+
 Autocorrelation
 ---------------
 .. autofunction:: autocorrelate
 
+
+.. _sec_cc:
+
 Cross-correlation
 -----------------
 .. autofunction:: correlate
 
+
+.. _sec_cc_numpy:
+
 Cross-correlation (NumPy)
 -------------------------
 .. autofunction:: correlate_numpy
 
+
+.. _sec_constants:
+
 Constants
 ---------
 .. autodata:: multipletau.core.ZERO_CUTOFF
 
+
+.. _sec_examples:
+
 Examples
 ========
 .. fancy_include:: compare_correlation_methods.py
 
 
+
+.. _sec_changelog:
+
+Changelog
+=========
+List of changes in-between nanite releases.
+
+.. include_changelog:: ../CHANGELOG

docs/requirements.txt

@@ -1,5 +1,4 @@
-mock
-sphinx==4.3.0
-sphinxcontrib.bibtex>=2.0
-sphinx_rtd_theme==1.0
+sphinx
+sphinxcontrib.bibtex
+sphinx_rtd_theme
 

multipletau/__init__.py

@@ -23,7 +23,7 @@
 
 Obtaining multipletau
 ---------------------
-If you have Python and :py:mod:`numpy` installed, simply run
+If you have Python and :py:mod:`numpy` installed, simply run::
 
    pip install multipletau