Switched Sphinx Markdown extension from Recommonmark to MyST.

docs/api.md

@@ -1,10 +1,9 @@
-API
-===
+# API
 
 Code documentation of the public application programming interface
 provided by this library.
 
-```eval_rst
+```{eval-rst}
 .. currentmodule:: kde_diffusion
 
 .. autofunction:: kde1d

docs/conf.py

@@ -4,17 +4,16 @@
 This folder contains the documentation source files that are to be
 rendered as a static web site by the documentation generator Sphinx.
 The rendering process is configured by this very script and would be
-triggered by running  `sphinx-build . rendered` on the command line,
-no matter the operating system. The rendered HTML then ends up in the
-sub-folder `rendered`, where `index.html` is the start page.
+triggered when running  `sphinx-build . output` on the command line.
+The rendered HTML then ends up in the `output` folder, wherein
+`index.html` is the start page.
 
 The documentation source comprises the `.md` files here, of which
-`index.md` maps to the start page, as well as the documentation strings
-in the package's source code for the API documentation.
-
-All text may use mark-up according to the CommonMark specification of
-the Markdown syntax. The Sphinx extension `reCommonMark` is used to
-convert Markdown to reStructuredText, Sphinx's native input format.
+`index.md` maps to the start page, as well as the doc-strings in the
+package's source code for the API documentation. The Markdown parser
+for `.md` files is MyST. For doc-strings it is CommonMark, which
+supports basic text formating, but no advanced features such as cross
+references.
 """
 __license__ = 'MIT'
 
@@ -23,19 +22,16 @@
 # Dependencies                         #
 ########################################
 
-import sphinx_rtd_theme                # Read-the-Docs theme
-import recommonmark                    # Markdown extension
-import recommonmark.transform          # Markdown transformations
 import commonmark                      # Markdown parser
-import re                              # regular expressions
-import sys                             # system specifics
 from unittest.mock import MagicMock    # mock imports
-from pathlib import Path               # file-system paths
+import sys                             # system specifics
+from pathlib import Path               # file-system path
 
 extensions = [
     'sphinx_rtd_theme',                # Register Read-the-Docs theme.
-    'recommonmark',                    # Accept Markdown as input.
+    'myst_parser',                     # Accept Markdown as input.
     'sphinx.ext.autodoc',              # Get documentation from doc-strings.
+    'sphinx.ext.autosummary',          # Create summaries automatically.
     'sphinx.ext.viewcode',             # Add links to highlighted source code.
     'sphinx.ext.mathjax',              # Render math via JavaScript.
 ]
@@ -54,47 +50,21 @@
 
 
 ########################################
-# Customization                        #
+# Doc-strings                          #
 ########################################
 
-def syntax_tweaks(lines):
-    """
-    Applies custom tweaks to the Markdown syntax.
-
-    Namely, converts the Unicode bullet character (•) to a standard
-    list-item marker (*) so that the CommomMark parser recognizes it
-    as such — which it regrettably doesn't.
-    """
-    tweaked = [re.sub(r'^([ \t]*)•', r'\1*', line) for line in lines]
-    return tweaked
-
-
-def source_files(app, docname, lines):
-    """Post-processes source files."""
-    pass
-
-
-def doc_strings(app, what, name, obj, options, lines):
-    """Converts doc-strings from Markdown to reStructuredText."""
-    tweaked  = syntax_tweaks(lines)
-    markdown = '\n'.join(tweaked)
-    parsed   = commonmark.Parser().parse(markdown)
-    restruct = commonmark.ReStructuredTextRenderer().render(parsed)
+def docstring(app, what, name, obj, options, lines):
+    """Converts doc-strings from (CommonMark) Markdown to reStructuredText."""
+    md  = '\n'.join(lines)
+    ast = commonmark.Parser().parse(md)
+    rst = commonmark.ReStructuredTextRenderer().render(ast)
     lines.clear()
-    lines += restruct.splitlines()
+    lines += rst.splitlines()
 
 
 def setup(app):
     """Configure customized text processing."""
-    app.connect('source-read', source_files)
-    app.connect('autodoc-process-docstring', doc_strings)
-    app.add_config_value('recommonmark_config', {
-        'auto_toc_tree_section': 'Contents',
-        'enable_math': True,
-        'enable_inline_math': True,
-        'enable_eval_rst': True,
-    }, True)
-    app.add_transform(recommonmark.transform.AutoStructify)
+    app.connect('autodoc-process-docstring', docstring)
 
 
 ########################################
@@ -111,26 +81,23 @@ def setup(app):
 license   = meta.__license__
 
 # Source parsing
-master_doc         = 'index'           # start page
-source_suffix      = ['.md', '.rst']   # valid source-file suffixes
-language           = None              # language for auto-generated content
-nitpicky           = True              # Warn about missing references?
+master_doc = 'index'                   # start page
+nitpicky   = True                      # Warn about missing references?
 
 # Code documentation
-default_role       = 'code'            # Back-ticks denote code in reST.
-add_module_names   = False             # Don't precede members with module name.
+add_module_names = False               # Don't prefix members with module name.
 autodoc_default_options = {
-    'members':       None,             # Include module/class members.
+    'members':       True,             # Include module/class members.
     'member-order': 'bysource',        # Order members as in source file.
 }
 
 # Output style
-html_theme       = 'sphinx_rtd_theme'  # Use Read-the-Docs theme.
-html_static_path = ['style']           # folders to include in output
-html_css_files   = ['custom.css']      # additional style files
+html_theme       = 'sphinx_rtd_theme'  # Use the Read-the-Docs theme.
 pygments_style   = 'trac'              # syntax highlighting style
+html_static_path = ['style']           # folders to include in output
+html_css_files   = ['custom.css']      # extra style files to apply
 
 # Output options
-html_copy_source    = False            # Copy documentation source files?
-html_show_copyright = False            # Show copyright notice in footer?
-html_show_sphinx    = False            # Show Sphinx blurb in footer?
+html_copy_source     = False           # Copy documentation source files?
+html_show_copyright  = False           # Show copyright notice in footer?
+html_show_sphinx     = False           # Show Sphinx blurb in footer?

docs/implementation.md

@@ -1,24 +1,24 @@
-Implementation
---------------
+# Implementation
 
 This Python library was developed based on the existing Matlab
-implementation for [1d][1] and [2d][2], which was used as the
+implementation for [1d][kde1d] and [2d][kde2d], which was used as the
 primary reference (albeit possibly in earlier versions previously
-stored at the same locations), and the [original paper][3] as a
+stored at the same locations), and the [original paper][paper] as a
 secondary source, mostly to understand the nomenclature and general
 idea behind the method.
 
 The Matlab implementation was first rewritten in Python to give the
 exact same result, including intermediate steps, for the same test
-case: a univariate normal sampling. See the `verification` folder in
-the [source-code repository][4] for details.
+case: a univariate normal sampling. See the [`verification`][verif]
+folder in the source-code [repository][repo] for details.
 
 Subsequently, the Python code was refactored in order to blend in
 better with the existing software ecosystem, namely by leveraging
 SciPy's forward and backward discrete cosine transformation for one
-or n dimensions, [`dct`][5]/[`dctn`][6] and [`idct`][7]/[`idctn`][8],
-as well as NumPy's [`histogram`][9] and [`histogram2d`][10], instead
-of the custom versions the Matlab reference employs.
+or n dimensions, [`dct`][dct]/[`dctn`][dctn] and
+[`idct`][idct]/[`idctn`][idctn], as well as NumPy's [`histogram`][hist]
+and [`histogram2d`][hist2d], instead of the custom versions the Matlab
+reference employs.
 
 The reference uses a cosine transformation with a weight for the very
 first component that is different from the one in any of the four types
@@ -40,8 +40,8 @@ This is consistent with results returned by other kernel density
 estimations, such as SciPy's, as well as NumPy's 2d-histogram function.
 When saving or displaying the 2d density as an image, a different
 memory layout is expected and the index order has to be reversed: y
-before x. This comes down to a simple transposition, i.e. adding `.T`
-in the code.
+before x. This comes down to a simple transposition, i.e. adding
+[`.T`][dotT] in the code.
 
 In very broad strokes, the method is this:
 * Bin the data on a regular grid.
@@ -54,13 +54,15 @@ In very broad strokes, the method is this:
 * Reverse transformation to obtain density estimation.
 
 
-[1]:  https://mathworks.com/matlabcentral/fileexchange/14034
-[2]:  https://mathworks.com/matlabcentral/fileexchange/17204
-[3]:  https://dx.doi.org/10.1214/10-AOS799
-[4]:  https://github.com/john-hennig/kde-diffusion
-[5]:  https://docs.scipy.org/doc/scipy/reference/generated/scipy.fft.dct.html
-[6]:  https://docs.scipy.org/doc/scipy/reference/generated/scipy.fft.dctn.html
-[7]:  https://docs.scipy.org/doc/scipy/reference/generated/scipy.fft.idct.html
-[8]:  https://docs.scipy.org/doc/scipy/reference/generated/scipy.fft.idctn.html
-[9]:  https://numpy.org/doc/1.18/reference/generated/numpy.histogram.html
-[10]: https://numpy.org/doc/1.18/reference/generated/numpy.histogram2d.html
+[kde1d]:   https://mathworks.com/matlabcentral/fileexchange/14034
+[kde2d]:   https://mathworks.com/matlabcentral/fileexchange/17204
+[paper]:   https://dx.doi.org/10.1214/10-AOS799
+[verif]:   https://github.com/John-Hennig/KDE-diffusion/tree/master/verification
+[repo]:    https://github.com/john-hennig/kde-diffusion
+[dct]:     https://docs.scipy.org/doc/scipy/reference/generated/scipy.fft.dct.html
+[dctn]:    https://docs.scipy.org/doc/scipy/reference/generated/scipy.fft.dctn.html
+[idct]:    https://docs.scipy.org/doc/scipy/reference/generated/scipy.fft.idct.html
+[idctn]:   https://docs.scipy.org/doc/scipy/reference/generated/scipy.fft.idctn.html
+[hist]:    https://numpy.org/doc/stable/reference/generated/numpy.histogram.html
+[hist2d]:  https://numpy.org/doc/stable/reference/generated/numpy.histogram2d.html
+[dotT]:    https://numpy.org/doc/stable/reference/generated/numpy.ndarray.T.html

docs/index.md

@@ -1,5 +1,4 @@
-KDE-diffusion
-=============
+# KDE-diffusion
 
 Kernel density estimation is a statistical method to infer the
 *true* probability density function that governs the distribution of
@@ -54,12 +53,11 @@ assumptions about the nature of the data.
 [7]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.gaussian_filter.html
 
 
-```eval_rst
-.. toctree::
-    :hidden:
+```{toctree}
+:hidden:
 
-    installation
-    usage
-    implementation
-    api
+installation
+usage
+implementation
+api
 ```

docs/installation.md

@@ -1,22 +1,16 @@
-Installation
-------------
+# Installation
 
 The library is [available on PyPI][1] and can be readily installed
-via `pip`.
-
-System-wide installation — recommended on Windows:
+via `pip`:
 ```none
 pip install KDE-diffusion
 ```
 
-Per-user installation — recommended on Linux and MacOS:
-```none
-pip install KDE-diffusion --user
-```
+Run `pip uninstall KDE-diffusion` in order to remove the package from
+your system.
 
 Requires [NumPy][2] and [SciPy][3], which `pip` will install
-automatically if they aren't already. Remove the library from your
-system with `pip uninstall KDE-diffusion`.
+automatically in case they are missing.
 
 
 [1]: https://pypi.org/project/KDE-diffusion/

docs/requirements.txt

@@ -0,0 +1,5 @@
+sphinx>=2.0.0
+sphinx_rtd_theme
+myst-parser
+commonmark
+docutils==0.16

docs/style/custom.css

@@ -1,12 +1,15 @@
 .section { text-align: justify }
-.pre { color:black }
+
+code.docutils > span.pre { color: black; font-weight: normal }
+p + div[class^="highlight"] { margin-top: -12px !important }
+
 .rst-content ul.simple li > p { margin-bottom: 0}
 .rst-content dd ul.simple li > p { margin-bottom: 0 !important }
 p + ul.simple { margin-top: -24px }
 dd p + ul.simple { margin-top: -12px }
+
 .rst-content ol.simple li > p { margin-bottom: 0}
 .rst-content dd ol.simple li > p { margin-bottom: 0 !important }
 p + ol.simple { margin-top: -24px }
 ol.simple ol.simple { margin-top: 0; margin-bottom: 0; }
 dd p + ol.simple { margin-top: -12px }
-p + div[class^="highlight"] { margin-top: -12px !important }

docs/usage.md

@@ -1,5 +1,4 @@
-Usage
------
+# Usage
 
 Code example for one-dimensional input data:
 
@@ -54,4 +53,5 @@ Images, however, are universally indexed the other way around: y before
 x. This is why the density in the example is transposed before being
 displayed.
 
+
 [1]: https://stackoverflow.com/a/56917343

tests/parent.py

@@ -5,5 +5,5 @@
 import sys
 from pathlib import Path
 
-folder = Path(__file__).parent.parent.absolute()
+folder = Path(__file__).parent.parent.resolve()
 sys.path.insert(0, str(folder))