docs!: switch to MyST-NB (#143)

.editorconfig

@@ -6,6 +6,9 @@ indent_style = space
 trim_trailing_whitespace = true
 insert_final_newline = true
 
+[Makefile]
+indent_style = tab
+
 [*.{py,toml}]
 indent_size = 4
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+**Describe the bug** A clear and concise description of what the bug is.
+
+**To Reproduce** Steps to reproduce the behavior:
+
+1.
+
+**Expected behavior** A clear and concise description of what you expected to
+happen.
+
+**Error log** If applicable, add an error log or screenshots to help explain
+your problem.
+
+**Desktop (please complete the following information):**
+
+- OS: [e.g. iOS]
+- Version [e.g. 22]
+
+**Additional context** Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[REQUEST] "
+labels: ""
+assignees: ""
+---
+
+**Is your feature request related to a problem? Please describe.** A clear and
+concise description of what the problem is. [Example: "I'm always frustrated
+when ..."]
+
+**Describe the solution you'd like** A clear and concise description of what
+you want to happen.
+
+**Describe alternatives you've considered** A clear and concise description of
+any alternative solutions or features you've considered.
+
+**Additional context** Add any other context or screenshots about the feature
+request here.

.github/workflows/cd.yml

@@ -0,0 +1,122 @@
+# cspell:ignore noreply pypa sdist
+
+name: CD
+
+on:
+  create:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+*"
+
+jobs:
+  test:
+    name: Run pytest
+    if: startsWith(github.ref, 'refs/tags')
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - macos-10.15
+          - ubuntu-18.04
+        python-version: [3.6, 3.7, 3.8]
+        exclude:
+          - os: macos-10.15
+            python-version: 3.6
+          - os: macos-10.15
+            python-version: 3.8
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[test]
+      - name: Test with pytest
+        env:
+          PYTEST_RUN_SLOW_TESTS: YES
+        run: pytest -n auto
+
+  documentation:
+    name: Build documentation and run notebooks
+    if: startsWith(github.ref, 'refs/tags')
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.7
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[doc]
+          sudo apt-get -y install pandoc graphviz
+      - name: Build documentation and run notebooks
+        working-directory: docs
+        env:
+          EXECUTE_NB: YES
+        run: make html
+      - name: Test doctests in docstrings
+        working-directory: docs
+        run: make ignore-warnings=1 doctest
+
+  style:
+    name: Style checks
+    if: startsWith(github.ref, 'refs/tags')
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.7
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+          sudo npm install -g cspell markdownlint-cli pyright
+      - name: Perform style checks
+        run: tox -e sty
+      - name: Check spelling
+        run: cspell $(git ls-files)
+      - name: Lint Markdown files
+        run: markdownlint .
+      - name: Run pyright
+        run: pyright
+
+  push:
+    name: Push to stable branch
+    if: startsWith(github.ref, 'refs/tags')
+    runs-on: ubuntu-18.04
+    needs:
+      - documentation
+      - style
+      - test
+    steps:
+      - uses: actions/checkout@master
+      - name: Push to stable branch
+        run: |
+          git config --global user.name "GitHub Action"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git push origin HEAD:refs/heads/stable -f
+
+  pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags')
+    needs: push
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - name: Set up Python 3.8
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.8
+      - name: Create distribution
+        run: python setup.py sdist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          user: __token__
+          password: ${{ secrets.pypi_password }}

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
           python -m pip install --upgrade pip
           pip install .[test]
       - name: Test with pytest-cov
-        run: pytest --cov=tensorwaves --cov-report=xml
+        run: pytest -n auto --cov=tensorwaves --cov-report=xml
       - uses: codecov/codecov-action@v1
         with:
           file: ./coverage.xml
@@ -67,9 +67,9 @@ jobs:
           python -m pip install --upgrade pip
           pip install .[test]
       - name: Test with pytest
-        run: pytest
+        run: pytest -n auto
       - name: Test example scripts
-        working-directory: examples/python
+        working-directory: examples
         run: python *.py # https://github.com/ComPWA/tensorwaves/issues/103
 
   documentation:
@@ -87,15 +87,15 @@ jobs:
           python -m pip install --upgrade pip
           pip install .[doc]
           pip install tensorflow-cpu
-          sudo apt-get -y install pandoc
+          sudo apt-get -y install pandoc graphviz
       - name: Build documentation and run notebooks
-        working-directory: doc
+        working-directory: docs
         env:
-          NBSPHINX_EXECUTE: YES
+          EXECUTE_NB: YES
         run: make html
       - name: Test doctests in docstrings
-        working-directory: doc
-        run: make doctest
+        working-directory: docs
+        run: make ignore-warnings=1 doctest
 
   style:
     name: Style checks

.github/workflows/linkcheck.yml

@@ -28,5 +28,5 @@ jobs:
           pip install .[doc]
           sudo apt-get -y install pandoc
       - name: Check external links
-        working-directory: doc
-        run: make linkcheck
+        working-directory: docs
+        run: make ignore-warnings=1 linkcheck

.gitignore

@@ -1,44 +1,47 @@
 # Output files
+*.json
 *.npy
 *.pdf
 *.png
 *.xml
 *.yaml
 *.yml
-!.github/*.yml
-!.github/*/*.yml
-!.gitpod.yml
-!.pre-commit-config.yaml
-!.readthedocs.yml
-!codecov.yml
-!environment.yml
-!examples/intensity-recipe.yaml
 
-# Build output
+# Build files
 *.egg-info/
-*.eggs/
 *build/
+.eggs/
 .fuse_*
 dist/
 version.py
 
-# Python temporary files
+# Temporary files
 *.pyc
+.condaenv.*
 .coverage
 .coverage.*
-.eggs/
 .ipynb_checkpoints/
 .mypy*/
 .pytest_cache/
-.tox/
 __pycache__/
 htmlcov/
 prof/
 
 # Virtual environments
-/*venv/
-condaenv.*.txt
+*venv/
+.tox/
+pyvenv*/
 
 # Settings
 .idea/
 **.code-workspace
+
+# Exceptions
+!.github/*.yml
+!.github/*/*.yml
+!.gitpod.yml
+!.pre-commit-config.yaml
+!.readthedocs.yml
+!codecov.yml
+!environment.yml
+!examples/intensity-recipe.yaml

.markdownlint.json

@@ -1,5 +1,5 @@
 {
-  "MD026": { "punctuation": ".,;:!。，；：！" },
+  "MD026": { "punctuation": ".,;:。，；：！" },
   "MD033": {
     "allowed_elements": ["br"]
   }

.pre-commit-config.yaml

@@ -9,7 +9,6 @@ repos:
     hooks:
       - id: check-ast
       - id: check-case-conflict
-      - id: check-docstring-first
       - id: check-json
       - id: check-merge-conflict
       - id: check-toml

.readthedocs.yml

@@ -2,7 +2,7 @@ version: 2
 
 sphinx:
   builder: html
-  configuration: doc/conf.py
+  configuration: docs/conf.py
   fail_on_warning: false
 
 formats:

.vscode/extensions.json

@@ -6,7 +6,9 @@
     "eamodio.gitlens",
     "editorconfig.editorconfig",
     "esbenp.prettier-vscode",
+    "executablebookproject.myst-highlight",
     "github.vscode-pull-request-github",
+    "joaompinto.vscode-graphviz",
     "lextudio.restructuredtext",
     "ms-python.python",
     "ms-python.vscode-pylance",

.vscode/settings.json

@@ -1,4 +1,7 @@
 {
+  "[ipynb]": {
+    "editor.formatOnSave": false
+  },
   "[json]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
@@ -44,15 +47,15 @@
   "python.linting.pylintEnabled": true,
   "python.linting.pylintUseMinimalCheckers": false,
   "python.testing.nosetestsEnabled": false,
-  "python.testing.pytestArgs": ["tests", "--no-cov"],
+  "python.testing.pytestArgs": ["--no-cov"],
   "python.testing.pytestEnabled": true,
   "python.testing.unittestEnabled": false,
-  "restructuredtext.builtDocumentationPath": "${workspaceFolder}/doc/_build/html",
-  "restructuredtext.confPath": "${workspaceFolder}/doc",
+  "restructuredtext.builtDocumentationPath": "${workspaceFolder}/docs/_build/html",
+  "restructuredtext.confPath": "${workspaceFolder}/docs",
   "rewrap.wrappingColumn": 79,
   "search.exclude": {
     "**/tests/**/__init__.py": true,
-    "doc/tox.ini": true,
+    "docs/tox.ini": true,
     "tests/tox.ini": true
   },
   "telemetry.enableCrashReporter": false,

CONTRIBUTING.md

@@ -1,4 +1,4 @@
 # How to contribute?
 
 See instructions at
-[tensorwaves.readthedocs.io/contribute](https://pwa.readthedocs.io/projects/tensorwaves/en/latest/contribute.html)!
+[tensorwaves.readthedocs.io/develop](https://pwa.readthedocs.io/projects/tensorwaves/en/latest/develop.html)!