Updated doc to myst-parser

doc/source/conf.py

@@ -1,15 +1,3 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
 import os
 import sys
 sys.path.insert(0, os.path.abspath('../..'))
@@ -48,39 +36,33 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-              'sphinx.ext.autodoc',
-              'sphinx.ext.autosummary',
-              'sphinx.ext.mathjax',
-              'sphinx.ext.viewcode',
-              'nbsphinx',
-              'nbsphinx_link',
-              'recommonmark',
-              'breathe',
-              'exhale',
-              ]
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+    'nbsphinx',
+    'nbsphinx_link',
+    'myst_parser',
+    'breathe',
+    'exhale',
+]
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "deflist",
+    "html_admonition",
+    "html_image",
+    "colon_fence",
+    "smartquotes",
+    "replacements",
+    "substitution",
+    "tasklist",
+]
 
 # avoid running the notebook's cells
 nbsphinx_execute = 'never'
 
-# to be able to add the README.md
-from m2r import MdInclude
-from recommonmark.transform import AutoStructify
-def setup(app):
-    config = {
-        # 'url_resolver': lambda url: github_doc_root + url,
-        'auto_toc_tree_section': 'Contents',
-        'enable_eval_rst': True,
-    }
-    app.add_config_value('recommonmark_config', config, True)
-    app.add_transform(AutoStructify)
-
-    # from m2r to make `mdinclude` work
-    app.add_config_value('no_underscore_emphasis', False, 'env')
-    app.add_config_value('m2r_parse_relative_links', False, 'env')
-    app.add_config_value('m2r_anonymous_references', False, 'env')
-    app.add_config_value('m2r_disable_inline_math', False, 'env')
-    app.add_directive('mdinclude', MdInclude)
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -90,7 +72,11 @@ def setup(app):
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'python_api/pumapy.rst', '**.ipynb_checkpoints']
 
 from unittest import mock
-MOCK_MODULES = ['TexGen.Core', 'dolfin', 'matplotlib', 'pyvista']
+MOCK_MODULES = ['TexGen.Core', 'dolfin', 'matplotlib', 'pyvista', 
+                'vtkmodules', 'vtkmodules.util', 'vtkmodules.util.numpy_support', 'vtkmodules.vtkIOXML', 'vtkmodules.vtkIOLegacy',
+                'skimage', 'skimage.transform', 'skimage.filters', 'skimage.morphology', 'skimage.segmentation', 'skimage.io',  
+                'scipy', 'scipy.ndimage', 'scipy.sparse', 'scipy.sparse.linalg', 
+                'scipy.spatial', 'scipy.spatial.transform', 'scipy.optimize']
 
 for module_name in MOCK_MODULES:
     sys.modules[module_name] = mock.Mock()

doc/source/cpp_api.md

@@ -0,0 +1,4 @@
+<!-- ```{eval-rst}
+.. include:: cpp_api/namespace_puma.rst
+.. include:: cpp_api/namespace_IterativeSolver.rst
+``` -->

doc/source/index.md

@@ -0,0 +1,33 @@
+# PuMA Documentation
+
+```{toctree}
+:maxdepth: 2
+:caption: Quick start
+
+readme.md
+```
+
+```{toctree}
+:maxdepth: 1
+:glob:
+:caption: Python API
+
+python_api.md
+```
+
+<!-- ```{toctree}
+:maxdepth: 2
+:glob:
+:caption: C++ API
+
+cpp_api.md
+``` -->
+
+```{toctree}
+:maxdepth: 1
+:glob:
+:caption: Tutorial
+
+readme_tutorial.md
+python_tutorials/*
+```

doc/source/python_api.md

@@ -0,0 +1,16 @@
+```{eval-rst}
+.. include:: python_api/pumapy.experimental.rst
+.. include:: python_api/pumapy.filters.rst
+.. include:: python_api/pumapy.generation.rst
+.. include:: python_api/pumapy.io.rst
+.. include:: python_api/pumapy.material_properties.rst
+.. include:: python_api/pumapy.physics_models.finite_element.rst
+.. include:: python_api/pumapy.physics_models.finite_volume.rst
+.. include:: python_api/pumapy.physics_models.particle.rst
+.. include:: python_api/pumapy.physics_models.rst
+.. include:: python_api/pumapy.physics_models.utils.rst
+.. include:: python_api/pumapy.rst
+.. include:: python_api/pumapy.segmentation.rst
+.. include:: python_api/pumapy.utilities.rst
+.. include:: python_api/pumapy.visualization.rst
+```

doc/source/readme.md

@@ -0,0 +1 @@
+```{include} ../../README.md

doc/source/readme_tutorial.md

@@ -0,0 +1 @@
+```{include} ../../tutorials/README.md

doc/sphinx_env.yml

@@ -1,24 +1,19 @@
 name: sphinx_rtd
 channels:
-  - anaconda
   - conda-forge
   - defaults
 dependencies:
-  - pip ==20.2.4
-  - sphinx ==3.5.4
-  - sphinx_rtd_theme ==0.4.3
-  - nbsphinx ==0.8.4
-  - nbsphinx-link ==1.3.0
-  - m2r ==0.2.1
-  - recommonmark ==0.6.0
-  - ipython ==7.24.1
-  - breathe ==4.30.0
+  - pip
+  - sphinx
+  - sphinx_rtd_theme
+  - nbsphinx
+  - nbsphinx-link
+  - ipython
+  - breathe
   - doxygen
-  - vtk
-  - scipy
-  - scikit-image
+  - cython
   - numpy
   - pandoc
-  - jinja2 <3.1
-  - pip:
-    - exhale ==0.2.3
+  - myst-parser
+  - jinja2
+  - exhale

setup.py

@@ -1,6 +1,7 @@
 from setuptools import setup, Command, find_packages
 from distutils.extension import Extension
 import numpy as np
+from Cython.Build import cythonize
 import os
 import re
 import ast
@@ -18,27 +19,12 @@ def run(self):
 
 
 # add cython code to the pumapy extensions
-try:
-    from Cython.Build import cythonize
-    extensions = cythonize([Extension("pumapy.generation.tpms_utils",
-                                      [os.path.join("python", "pumapy", "generation", "tpms_utils.pyx")]),
-                            Extension("pumapy.physics_models.finite_volume.isotropic_conductivity_utils",
-                                      [os.path.join("python", "pumapy", "physics_models", "finite_volume", "isotropic_conductivity_utils.pyx")]),
-                            Extension("pumapy.physics_models.finite_volume.anisotropic_conductivity_utils",
-                                      [os.path.join("python", "pumapy", "physics_models", "finite_volume", "anisotropic_conductivity_utils.pyx")]),
-                            Extension("pumapy.physics_models.finite_volume.elasticity_utils",
-                                      [os.path.join("python", "pumapy", "physics_models", "finite_volume", "elasticity_utils.pyx")]),
-                            ])
-except ImportError:  # if cython not found, use existing C code
-    extensions = [Extension("pumapy.generation.tpms_utils",
-                            [os.path.join("python", "pumapy", "generation", "tpms_utils.c")]),
-                  Extension("pumapy.physics_models.finite_volume.isotropic_conductivity_utils",
-                            [os.path.join("python", "pumapy", "physics_models", "finite_volume", "isotropic_conductivity_utils.c")]),
-                  Extension("pumapy.physics_models.finite_volume.anisotropic_conductivity_utils",
-                            [os.path.join("python", "pumapy", "physics_models", "finite_volume", "anisotropic_conductivity_utils.c")]),
-                  Extension("pumapy.physics_models.finite_volume.elasticity_utils",
-                            [os.path.join("python", "pumapy", "physics_models", "finite_volume", "elasticity_utils.c")]),
-                  ]
+extensions = cythonize([
+    Extension("pumapy.generation.tpms_utils", [os.path.join("python", "pumapy", "generation", "tpms_utils.pyx")]),
+    Extension("pumapy.physics_models.finite_volume.isotropic_conductivity_utils", [os.path.join("python", "pumapy", "physics_models", "finite_volume", "isotropic_conductivity_utils.pyx")]),
+    Extension("pumapy.physics_models.finite_volume.anisotropic_conductivity_utils", [os.path.join("python", "pumapy", "physics_models", "finite_volume", "anisotropic_conductivity_utils.pyx")]),
+    Extension("pumapy.physics_models.finite_volume.elasticity_utils", [os.path.join("python", "pumapy", "physics_models", "finite_volume", "elasticity_utils.pyx")]),
+])
 
 with open("README.md", "r", encoding="utf-8") as fh:
     long_description = fh.read()