Sphinx use myst-nb (#830)

* use myst-nb to execute and render notebooks
* convert remaining documents from rst to md
* mv src files to src sub dir
* mv tutorials to doc/src
* mv makefile to doc/
* use myst include directive
* clean up gitignore
* fix warning
* added symlink to tutorials
* [gha/static_analysis] mypy only checks source folder
* ignore RUF101 in conf.py
* [gha/docs] fix path
* [sphinx/conf] updated source suffixes
* pin sphinx-autodoc-typehints 🙏
* update changelog action
* do not link to tutorials, just refer to them as plain text.
* add plugin to render json as raw html
* install plugin in rtd_env
* increase nb execution timeout
* [rtd] fix conf path
* pin docutils >=0.19

.flake8

@@ -16,5 +16,5 @@ max-line-length = 88
 select = C,E,F,W,B,B950 # black formatting options
 exclude =
     __init__.py
-    doc/conf.py
+    doc/src/conf.py
 no-accept-encodings = True

.github/workflows/changelog.yml

@@ -16,5 +16,5 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
-      - name: Grep for PR number in CHANGELOG.rst
-        run: grep -P ':pull:`${{github.event.number}}`' CHANGELOG.rst
+      - name: Grep for PR number in CHANGELOG.md
+        run: grep -P '{pull}`${{github.event.number}}`' CHANGELOG.md

.github/workflows/docs.yml

@@ -57,12 +57,8 @@ jobs:
       - name: install weldx kernel
         run: ipython kernel install --user --name=weldx
 
-      - name: set notebook execution
-        if: (github.event_name == 'workflow_dispatch')
-        run: echo "nbsphinx_execute=${{ github.event.inputs.nbsphinx_execute }}" >> $GITHUB_ENV
-
       - name: Build docs
-        run: sphinx-build -W -n -b html -d build/doctrees doc build/html --keep-going -j 2 -D nbsphinx_execute=${{ env.nbsphinx_execute }}
+        run: sphinx-build -W -n -b html -d build/doctrees doc/src build/html --keep-going -j 2
 
       - uses: actions/upload-artifact@v3
         if: |

.github/workflows/static_analysis.yml

@@ -68,4 +68,4 @@ jobs:
 
       - name: run mypy
         run: |
-          mypy --install-types --non-interactive .
+          mypy --install-types --non-interactive weldx/

.gitignore

@@ -72,10 +72,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-doc/_build/
-build/
-
 # PyBuilder
 target/
 

.pre-commit-config.yaml

@@ -63,6 +63,6 @@ repos:
     rev: v2.2.2
     hooks:
       - id: codespell
-        exclude: doc/legal-notice.rst
+        exclude: doc/src/legal-notice.md
         args:
           - -L ro

.readthedocs.yml

@@ -17,7 +17,7 @@ build:
 # Build documentation in the doc/ directory with Sphinx
 sphinx:
   builder: html
-  configuration: doc/conf.py
+  configuration: doc/src/conf.py
   fail_on_warning: true
 #
 ## List of submodules to be included.