docs!: migrate to MyST-NB (#32)

.editorconfig

@@ -3,8 +3,11 @@ root = true
 [*]
 end_of_line = lf
 indent_style = space
-insert_final_newline = true
 trim_trailing_whitespace = true
+insert_final_newline = true
+
+[Makefile]
+indent_style = tab
 
 [Makefile]
 indent_style = tab

.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,103 @@
+# 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

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-# cspell:ignore markdownlint
+# cspell:ignore
 
 name: CI
 
@@ -7,10 +7,16 @@ on:
     branches: [master]
   pull_request:
     branches: [master]
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
 
 jobs:
   documentation:
-    name: Build and check documentation
+    name: Build documentation and run notebooks
+    if: github.event.pull_request.draft == false
     runs-on: ubuntu-18.04
     steps:
       - uses: actions/checkout@v2
@@ -22,12 +28,14 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install .[doc]
-          sudo apt-get -y install pandoc
-      - name: Build HTML-pages
+          sudo apt-get -y install pandoc graphviz
+      - name: Build documentation and run notebooks
+        working-directory: docs
         run: make html
 
   style:
     name: Style checks
+    if: github.event.pull_request.draft == false
     runs-on: ubuntu-18.04
     steps:
       - uses: actions/checkout@v2
@@ -39,10 +47,12 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install .[dev]
-          sudo npm install -g cspell markdownlint-cli
+          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

.github/workflows/linkcheck.yml

@@ -5,10 +5,16 @@ on:
     branches: [master]
   pull_request:
     branches: [master]
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
 
 jobs:
-  style:
+  check_links:
     name: Check external links
+    if: github.event.pull_request.draft == false
     runs-on: ubuntu-18.04
     steps:
       - uses: actions/checkout@v2
@@ -22,4 +28,5 @@ jobs:
           pip install .[doc]
           sudo apt-get -y install pandoc
       - name: Check external links
-        run: make linkcheck
+        working-directory: docs
+        run: make ignore-warnings=1 linkcheck

.gitignore

@@ -1,26 +1,21 @@
-# Temporary files
-.ipynb_checkpoints/
-condaenv.*
-
-# Build output
+# Build files
 *.egg-info/
 *build/
+.eggs/
 .fuse_*
 dist/
-htmlcov/
 version.py
 
-# Python temporary files
-*.egg-info/
+# Temporary files
 *.pyc
+*condaenv.*
 .coverage
 .coverage.*
-.eggs/
 .ipynb_checkpoints/
 .mypy*/
 .pytest_cache/
-.tox/
 __pycache__/
+htmlcov/
 prof/
 
 # Virtual environments
@@ -29,5 +24,5 @@ prof/
 pyvenv*/
 
 # Settings
-**.code-workspace
 .idea/
+**.code-workspace

.gitpod.yml

@@ -1,5 +1,3 @@
-# cspell:ignore prebuilds
-
 tasks:
   - init: pip install -e .[dev]
 

.readthedocs.yml

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

.vscode/extensions.json

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

.vscode/settings.json

@@ -2,6 +2,9 @@
   "[bibtex]": {
     "editor.formatOnSave": false
   },
+  "[ipynb]": {
+    "editor.formatOnSave": false
+  },
   "[json]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
@@ -37,17 +40,20 @@
   "python.analysis.diagnosticMode": "workspace",
   "python.formatting.provider": "black",
   "python.languageServer": "Pylance",
+  "python.linting.banditEnabled": false,
   "python.linting.enabled": true,
   "python.linting.flake8Enabled": true,
   "python.linting.mypyEnabled": true,
   "python.linting.pydocstyleEnabled": true,
+  "python.linting.pylamaEnabled": false,
   "python.linting.pylintCategorySeverity.refactor": "Information",
   "python.linting.pylintEnabled": true,
   "python.linting.pylintUseMinimalCheckers": false,
   "python.testing.nosetestsEnabled": false,
   "python.testing.pytestEnabled": false,
   "python.testing.unittestEnabled": false,
-  "restructuredtext.builtDocumentationPath": "${workspaceFolder}/doc/_build/html",
+  "restructuredtext.builtDocumentationPath": "${workspaceFolder}/docs/_build/html",
+  "restructuredtext.confPath": "${workspaceFolder}/doc",
   "rewrap.wrappingColumn": 79,
   "telemetry.enableCrashReporter": false,
   "telemetry.enableTelemetry": false,

CONTRIBUTING.md

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