Merge pull request #36 from pyiron/myst_docs

Readthedocs render

.binder/postBuild

@@ -24,7 +24,6 @@ if [ -d "${HOME}/pyiron_ontology" ]; then
             ${HOME}/CONTRIBUTING.rst \
             ${HOME}/LICENSE \
             ${HOME}/MANIFEST.in \
-            ${HOME}/README.md \
             ${HOME}/setup.cfg \
             ${HOME}/setup.py \
             ${HOME}/versioneer.py

.ci_support/environment-docs.yml

@@ -0,0 +1,7 @@
+channels:
+- conda-forge
+dependencies:
+  - myst-parser
+  - sphinxcontrib-mermaid
+  - sphinx-gallery
+  - sphinx-rtd-theme

.github/workflows/push-pull.yml

@@ -12,5 +12,6 @@ jobs:
     uses: pyiron/actions/.github/workflows/push-pull-main.yml@main
     secrets: inherit
     with:
+      docs-env-files: .ci_support/environment.yml .ci_support/environment-docs.yml
       notebooks-env-files: .ci_support/environment.yml .ci_support/environment-pyiron_atomistics.yml .ci_support/environment-lammps.yml
       tests-env-files: .ci_support/environment.yml .ci_support/environment-pyiron_atomistics.yml

.readthedocs.yml

@@ -9,6 +9,10 @@ build:
    os: ubuntu-20.04
    tools:
      python: 'mambaforge-4.10'
+     nodejs: "16"
+   jobs:
+     post_install:
+       - npm install -g @mermaid-js/mermaid-cli
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -24,3 +28,9 @@ formats: all
 # Install pyiron from conda 
 conda:
   environment: docs/environment.yml
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .

docs/conf.py

@@ -34,14 +34,37 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['nbsphinx', 'sphinx.ext.mathjax', 'sphinx.ext.autodoc', 'sphinx.ext.viewcode',
-              'sphinx.ext.autosummary', 'sphinx.ext.napoleon']
+extensions = [
+    'sphinxcontrib.mermaid',
+    'myst_parser',
+    'nbsphinx',
+    'sphinx_gallery.load_style',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.imgconverter',
+]
+myst_fence_as_directive = ["mermaid"]
+# optional to use directive options
+myst_enable_extensions = ["attrs_block"]
+mermaid_params = ['-p' 'puppeteer-config.json']
+mermaid_output_format = "png"
+
+nbsphinx_thumbnails = {
+    'source/notebooks/example': "_static/pyiron-logo-dark.png",
+    'source/notebooks/pizza': "_static/pyiron-logo-dark.png",
+}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown'
+}
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -279,7 +302,7 @@
    u'pyiron Documentation',
    u'Max-Planck-Institut für Eisenforschung GmbH - Computational Materials Design (CM) Department',
    'pyiron_ontology',
-   'One line description of project.',
+   'Ontologies for guided workflow design.',
    'Miscellaneous'),
 ]
 

docs/environment.yml

@@ -8,3 +8,7 @@ dependencies:
 - owlready2 =0.45
 - pandas =2.1.4
 - pint =0.23
+- myst-parser
+- sphinxcontrib-mermaid
+- sphinx-gallery
+- sphinx-rtd-theme

docs/index.rst

@@ -9,4 +9,5 @@
 .. toctree::
    :hidden:
 
+   source/examples.rst
    source/indices.rst

docs/puppeteer-config.json

@@ -0,0 +1,3 @@
+{
+  "args": ["--no-sandbox"]
+}

docs/source/examples.rst

@@ -0,0 +1,11 @@
+.. _examples:
+
+
+Example Notebooks
+=================
+
+.. nbgallery::
+   :maxdepth: 2
+   :glob:
+
+   notebooks/*

docs/source/indices.rst

@@ -9,4 +9,4 @@ API Documentation
 
 
 .. toctree::
-   :maxdepth:2
+   :maxdepth: 2