move from recommonmark to myst

Author: croth1

.ci_scripts/environment.yml

@@ -4,13 +4,12 @@ channels:
 dependencies:
   - python=3
   - conda-smithy
-  - sphinx<3
-  - docutils<0.18
+  - sphinx
   - cloud_sptheme
   - sphinxcontrib-fulltoc
   - make
   - xonsh
-  - recommonmark
+  - myst-parser
   - pyyaml
   - jinja2
   - requests

.ci_scripts/update_docs

@@ -26,7 +26,10 @@ rm -rf docs/
 python .ci_scripts/generate_cfep_index.py
 
 pushd src
-make html
+
+# -W --keep-going: list all warnings but fail build in case there are any
+# -n: check validity of all links
+make html SPHINXOPTS="-W --keep-going -n"
 mv _build/html ../docs
 rm -rf _build
 popd

src/conf.py

@@ -17,7 +17,6 @@
 import datetime
 
 import cloud_sptheme as csp
-import recommonmark.parser
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -33,6 +32,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'myst_parser',
     'sphinx.ext.todo',
     'sphinxcontrib.fulltoc',
     'sphinxcontrib.newsfeed',
@@ -41,10 +41,6 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# Transpile markdown into rest
-source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
-}
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -86,7 +82,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.