Switched Sphinx Markdown extension from Recommonmark to MyST.

This allows cross-linking to sections, not just chapters,
as well as better support for Sphinx directives, and also
renders a tad nicer.

docs/api.md

@@ -1,11 +1,9 @@
-API
----
+# API
 
-Code documentation of the application programming interface provided
-by this library.
-
-```eval_rst
+Code documentation of the public application programming interface
+provided by this library.
 
+```{eval-rst}
 .. currentmodule:: mph
 
 .. autosummary::

docs/conf.py

@@ -4,16 +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 . path/to/output` on the command
-line, no matter the operating system. The rendered HTML then ends up
-in the output folder, wherein `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'
 
@@ -22,17 +22,14 @@
 # Dependencies                         #
 ########################################
 
-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.
@@ -53,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)
 
 
 ########################################
@@ -110,25 +81,24 @@ 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':       True,             # Include module/class members.
-    'member-order': 'bysource'}        # Order members as in source file.
+    'member-order': 'bysource',        # Order members as in source file.
+}
 
 # Output style
-html_theme       = 'sphinx_rtd_theme'  # Read-the-Docs theme
+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
-pygments_style   = 'trac'              # syntax highlighting style
 
 # 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?
+myst_heading_anchors = 2               # Generate link anchors for sections.
+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/demonstrations.md

@@ -1,7 +1,6 @@
-Demonstrations
---------------
+# Demonstrations
 
-### Busbar
+## Busbar
 
 ["Electrical Heating in a Busbar"][busbar] is an example model used
 in the tutorial in ["Introduction to Comsol Multiphysics"][intro] and
@@ -37,7 +36,7 @@ or width `wbb` of the busbar.
 [intro]: https://www.comsol.com/documentation/IntroductionToCOMSOLMultiphysics.pdf
 
 
-### Compacting models
+## Compacting models
 
 We usually save models to disk after we have solved them, which
 includes the solution and mesh data in the file. This is convenient
@@ -72,7 +71,7 @@ not meant to be included.
 [demos]: https://github.com/John-Hennig/MPh/tree/master/demos
 
 
-### Multiple processes
+## Multiple processes
 
 As explained in [Limitations](limitations), we cannot run more than
 one Comsol session inside the same Python process. But we *can* start
@@ -204,7 +203,7 @@ as a script.
 [subpr]: https://docs.python.org/3/library/subprocess.html
 
 
-### Creating models: Java style
+## Creating models: Java style
 
 The primary focus of MPh is to automate the simulation workflow, like
 running parameter sweeps or optimization routines with customized,
@@ -303,7 +302,7 @@ Java, or Matlab project.
 [blog]: https://www.comsol.com/blogs/automate-modeling-tasks-comsol-api-use-java
 
 
-### Creating models: Python style
+## Creating models: Python style
 
 The example from the previous section can be expressed in more
 "pythonic" syntax if we ignore the Java layer and only use methods

docs/index.md

@@ -1,5 +1,4 @@
-MPh
-===
+# MPh
 Pythonic scripting interface for Comsol Multiphysics
 
 [Comsol][comsol] is a commercial software application that is widely
@@ -26,13 +25,12 @@ and sells the simulation software.
 [jpype]:  https://pypi.org/project/JPype1
 
 
-```eval_rst
-.. toctree::
-    :hidden:
+```{toctree}
+:hidden:
 
-    installation
-    tutorial
-    limitations
-    demonstrations
-    api
+installation
+tutorial
+limitations
+demonstrations
+api
 ```

docs/installation.md

@@ -1,5 +1,4 @@
-Installation
-------------
+# Installation
 
 MPh is [available on PyPI][pypi] and can be readily installed via
 ```none

docs/limitations.md

@@ -1,7 +1,6 @@
-Limitations
------------
+# Limitations
 
-### Java bridge
+## Java bridge
 
 MPh is built on top of the Python-to-Java bridge [JPype][jpype].
 It is JPype that allows us to look at Comsol's Java API and run the
@@ -15,7 +14,7 @@ in parallel, distributed over independent processor cores in an effort
 to achieve maximum speed-up of a parameter sweep, they have to be
 started as separate Python (sub-)processes. This is a feasible
 work-around, but a limitation nonetheless. Refer to section  ["Multiple
-processes"](demonstrations#multiple-process) for a demonstration.
+processes"](demonstrations.md#multiple-processes) for a demonstration.
 
 For the same reason, the [test suite][tests] that comes with MPh fails
 when collected and run via the testing framework [pyTest][pytest].
@@ -36,7 +35,7 @@ A number of Java methods exposed by Comsol are inexplicably missing
 from the Python encapsulation.)
 
 
-### Platform differences
+## Platform differences
 
 The Comsol API offers two distinct ways to run a simulation session
 on the local machine. One may either start a "stand-alone" client,

docs/requirements.txt

@@ -1,5 +1,4 @@
 sphinx>=2.0.0
 sphinx_rtd_theme
-recommonmark
+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/tutorial.md

@@ -1,5 +1,4 @@
-Tutorial
---------
+# Tutorial
 
 To follow along with this tutorial in an interactive Python session,
 if you wish to do so, make sure you have downloaded the [demonstration
@@ -16,7 +15,7 @@ Comsol platform, but not for any add-on module beyond that.
 ![](images/capacitor.png)
 
 
-### Starting Comsol
+## Starting Comsol
 
 In the beginning was the client. And the client was with Comsol. And
 the client was Comsol. So let there be a Comsol client.
@@ -41,7 +40,7 @@ potential of your simulation hardware, you will need to run multiple
 Python sessions, one for each client.
 
 
-### Managing models
+## Managing models
 
 Now that we have the client up and running, we can tell it to load a
 model file.
@@ -81,7 +80,7 @@ Or we could remove all models at once — restart from a clean slate.
 ```
 
 
-### Inspecting models
+## Inspecting models
 
 Let's have a look at the parameters defined in the model.
 ```python
@@ -133,7 +132,7 @@ may also set up different models to be automated by the same script.
 No problem, as long as your naming scheme is consistent throughout.
 
 
-### Modifying parameters
+## Modifying parameters
 
 As we have learned from the list above, the model defines a parameter
 named `d` that denotes the electrode spacing. If we know a parameter's
@@ -165,7 +164,7 @@ away.
 >>> model.build()
 ```
 
-### Running simulations
+## Running simulations
 
 To solve the model, we need to create a mesh. This would also be taken
 care of automatically, but let's make sure this critical step passes
@@ -196,7 +195,7 @@ studies at once, or rather, all of the studies defined in the model.
 ```
 
 
-### Evaluating results
+## Evaluating results
 
 Let's see what we found out and evaluate the electrostatic capacitance,
 i.e. at zero time or infinite frequency.
@@ -287,7 +286,7 @@ of this library does not start with a 1 —, just to keep things simple
 and clean.
 
 
-### Saving results
+## Saving results
 
 To save the model we just solved, along with its solution, just do:
 ```python