diff --git a/.editorconfig b/.editorconfig
index 167b4f18..e3481199 100644
--- a/.editorconfig
+++ b/.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
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 00000000..390001de
--- /dev/null
+++ b/.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.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 00000000..e10461af
--- /dev/null
+++ b/.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.
diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
new file mode 100644
index 00000000..ec97c507
--- /dev/null
+++ b/.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
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 87b93293..dd6c4038 100644
--- a/.github/workflows/ci.yml
+++ b/.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
diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml
index 874658a7..ebc41369 100644
--- a/.github/workflows/linkcheck.yml
+++ b/.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
diff --git a/.gitignore b/.gitignore
index ad14ed65..524b7b92 100644
--- a/.gitignore
+++ b/.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
diff --git a/.gitpod.yml b/.gitpod.yml
index 603ddd07..8d64240c 100644
--- a/.gitpod.yml
+++ b/.gitpod.yml
@@ -1,5 +1,3 @@
-# cspell:ignore prebuilds
-
 tasks:
   - init: pip install -e .[dev]
 
diff --git a/.readthedocs.yml b/.readthedocs.yml
index 5b37e32f..684468e8 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,7 +1,8 @@
 version: 2
 
 sphinx:
-  configuration: doc/conf.py
+  builder: html
+  configuration: docs/conf.py
   fail_on_warning: false
 
 formats:
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index a5744f7c..79277320 100644
--- a/.vscode/extensions.json
+++ b/.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",
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 2a25272f..7334cc7e 100644
--- a/.vscode/settings.json
+++ b/.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,
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..34bb365d
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,4 @@
+# How to contribute?
+
+See instructions at
+[pwa.readthedocs.io/develop](https://pwa.readthedocs.io/develop.html)!
diff --git a/cspell.json b/cspell.json
index c611e107..54827dda 100644
--- a/cspell.json
+++ b/cspell.json
@@ -6,6 +6,7 @@
         "xml"
     ],
     "flagWords": [
+        "analyse",
         "colour",
         "comparision",
         "favour",
@@ -20,17 +21,18 @@
         "*.rst_t",
         "*.svg",
         ".gitignore",
+        ".gitpod.*",
         ".pre-commit-config.yaml",
         ".pylintrc",
         ".readthedocs.yml",
         ".vscode/*",
         ".vscode/.gitignore",
         "Makefile",
-        "_templates/*",
-        "commitlint.config.js",
-        "conf.py",
         "cspell.json",
+        "docs/_templates/*",
+        "docs/conf.py",
         "pyproject.toml",
+        "pyrightconfig.json",
         "setup.cfg",
         "setup.py",
         "tox.ini"
@@ -44,6 +46,8 @@
         "clebsch",
         "conda",
         "dalitz",
+        "docstrings",
+        "doctest",
         "doxygen",
         "flatt",
         "flatté",
@@ -66,17 +70,25 @@
         "arange",
         "autopep",
         "codemirror",
+        "commitlint",
+        "doctests",
+        "eval",
         "expertsystem",
+        "genindex",
+        "graphviz",
         "htmlcov",
         "infty",
         "ipython",
         "isort",
+        "jupyterlab",
         "kernelspec",
         "linkcheck",
+        "macos",
         "markdownlint",
         "mathrm",
         "maxdepth",
         "mkdir",
+        "modindex",
         "multiplets",
         "nbconvert",
         "nbformat",
@@ -86,16 +98,20 @@
         "pandoc",
         "propto",
         "pycompwa",
+        "pydocstyle",
         "pygments",
         "pylint",
         "pypi",
         "pyplot",
+        "pyproject",
+        "pyright",
         "pytest",
         "rarita",
         "rebased",
         "rightarrow",
         "rtfd",
         "scikit",
+        "seealso",
         "setuptools",
         "tensorwaves",
         "toctree",
diff --git a/doc/index.rst b/doc/index.rst
deleted file mode 100644
index 41fcd22e..00000000
--- a/doc/index.rst
+++ /dev/null
@@ -1,69 +0,0 @@
-.. title:: Welcome
-
-Welcome to the Partial Wave Analysis pages!
-===========================================
-
-.. list-table::
-
-  * - .. image:: https://readthedocs.org/projects/pwa/badge/?version=latest
-        :alt: Documentation build status
-        :target: https://pwa.readthedocs.io
-
-      .. image:: https://img.shields.io/badge/License-GPLv3+-blue.svg
-        :alt: GPLv3+ license
-        :target: https://www.gnu.org/licenses/gpl-3.0-standalone.html
-
-  * - .. image:: https://github.com/ComPWA/PWA-pages/workflows/CI/badge.svg
-        :alt: CI status
-        :target: https://github.com/ComPWA/PWA-pages/actions?query=branch%3Amaster+workflow%3A%22CI%22
-
-      .. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
-        :target: https://github.com/pre-commit/pre-commit
-        :alt: pre-commit
-
-      .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-        :alt: Code style: black
-        :target: https://github.com/psf/black
-
-      .. image:: https://camo.githubusercontent.com/687a8ae8d15f9409617d2cc5a30292a884f6813a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f64655f7374796c652d70726574746965722d6666363962342e7376673f7374796c653d666c61742d737175617265
-        :alt: Code style: Prettier
-        :target: https://prettier.io
-
-.. warning::
-  These pages and are **under development**.
-
-The PWA Software Pages serve two purposes:
-
-1. They aim to bring together the many Partial Wave Analysis frameworks out
-   there on the market through interlinked documentation.
-
-2. They provide a dynamic platform to collect and maintain knowledge on both
-   PWA theory and software tools.
-
-As such, the pages consist three main components: :doc:`theory <theory>`,
-:doc:`analysis techniques <analysis>`, and :doc:`software <software>`. The
-:doc:`theory pages <theory>` are to be a collection of the basics of PWA
-theory, along with references to more in-depth sources. This is useful, because
-it is often difficult for newcomers to find their way around in the growing
-amount of PWA literature and experimental results. The :doc:`analysis section
-<analysis>` visits some of the common statistics techniques that you need to be
-familiar with to do PWA (and event selection more generally). The
-:doc:`software pages <software>` serve as a guide through the available
-software tools that are relevant to PWA software development.
-
-.. toctree::
-  :maxdepth: 2
-
-  theory
-  analysis
-  software
-
-.. toctree::
-  :maxdepth: 1
-  :caption: Related projects
-  :hidden:
-
-  PWA Expert System <http://expertsystem.rtfd.io>
-  TensorWaves <http://tensorwaves.rtfd.io>
-  TF-PWA <http://tf-pwa.rtfd.io>
-  pycompwa <https://compwa.github.io>
diff --git a/doc/theory/formalisms.rst b/doc/theory/formalisms.rst
deleted file mode 100644
index 49edabdc..00000000
--- a/doc/theory/formalisms.rst
+++ /dev/null
@@ -1,100 +0,0 @@
-Formalisms
-==========
-
-.. warning::
-  These pages and are **under development**.
-
-Helicity Formalism
-------------------
-
-- Lorentz-invariance of helicity operator
-
-- Types
-
-  - Two-body decay amplitude
-  - Sequential two-body decay amplitude
-
-- Definition of angles
-
-  - Production angle
-  - Helicity angle
-  - Treiman-Yang angle
-  - Overview of kinematic variables
-
-- Dynamics:
-
-  - Wigner-D functions
-  - Clebsch-Gordan coefficients
-
-- Kinematic variables
-- An example
-
-.. admonition:: The old text
-  :class: dropdown
-
-  Two particle states are the key element here. With these one can construct
-  states of total spin $J$ and projection $M$.
-
-  The probability amplitude of a state with spin J and projection M decaying
-  into two particles 1 and 2 with helicities $\lambda_i$ and momentum $\vec{p}$
-  in the cms frame is given by :cite:`chungSpinFormalismsUpdated2014`, p.16.
-
-  .. math::
-
-    two body decay amplitude here
-
-  In the helicity formalism sequential two body decays are easy to handle
-
-  .. math::
-
-    seq two body decay amplitude here
-
-  Then show explicitly what ComPWA implements and which components correspond
-  to what part in the equation. So we would refer in the Doxygen docs to
-
-  - the Wigner D functions
-
-  - the Kinematics class
-
-  - the IntensityBuilderXML with the two functions createSequentialAmplitudeFT
-    createHelicityDecayFT
-
-  - the dynamical functions
-
-  - the phase space element calculations?
-
-  https://compwa.github.io/ComPWA/classComPWA_1_1Physics_1_1IntensityBuilderXML.html
-
-
-Canonical Formalism
--------------------
-
-.. admonition:: The old text
-  :class: dropdown
-
-  The canonical formalism gives access to the orbital angular momentum $L$ and
-  the coupled Spin $S$ arising from a two particle state.
-
-  There is a simple connection between the two formalism. Show that here
-
-  This expression is simply inserted into equation () and that is it!
-
-  The choice of the formalism depends on the physics process being analyzed.
-  Give an example here.
-
-
-Lorentz-invariant Formalisms
-----------------------------
-
-Rarita-Schwinger
-""""""""""""""""
-
-
-Other Spin Formalisms
----------------------
-
-(Covariant) Tensor Formalisms
-"""""""""""""""""""""""""""""
-
-Spin-projection formalisms
-""""""""""""""""""""""""""
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 00000000..0209b04a
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,5 @@
+*.doctree
+*.inv
+*build/
+api/
+pwa_pages.svg
diff --git a/Makefile b/docs/Makefile
similarity index 81%
rename from Makefile
rename to docs/Makefile
index e5f80a2f..5bd46973 100644
--- a/Makefile
+++ b/docs/Makefile
@@ -3,10 +3,15 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?= -T -W --keep-going
+SPHINXOPTS    ?= -T --color
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = doc
-BUILDDIR      = build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+ifdef ignore-warnings
+else
+	SPHINXOPTS += -W --keep-going
+endif
 
 # Put it first so that "make" without argument is like "make help".
 help:
diff --git a/docs/_templates/genindex.html b/docs/_templates/genindex.html
new file mode 100644
index 00000000..21849ec3
--- /dev/null
+++ b/docs/_templates/genindex.html
@@ -0,0 +1,55 @@
+{% macro indexentries(firstname, links) %} {%- if links -%}
+<a href="{{ links[0][1] }}">
+  {%- if links[0][0] %}<strong
+    >{% endif -%} {{ firstname|e }} {%- if links[0][0] %}</strong
+  >{% endif -%}
+</a>
+
+{%- for ismain, link in links[1:] -%} ,
+<a href="{{ link }}"
+  >{% if ismain %}<strong
+    >{% endif -%} [{{ loop.index }}] {%- if ismain %}</strong
+  >{% endif -%}
+</a>
+{%- endfor %} {%- else %} {{ firstname|e }} {%- endif %} {% endmacro %} {%-
+extends "layout.html" %} {% set title = _('Index') %} {% block body %}
+
+<h1 id="index">{{ _('Index') }}</h1>
+
+<div class="genindex-jumpbox">
+  {% for key, dummy in genindexentries -%}
+  <a href="#{{ key }}"><strong>{{ key }}</strong></a>
+  {% if not loop.last %}| {% endif %} {%- endfor %}
+</div>
+
+{%- for key, entries in genindexentries %}
+<h2 id="{{ key }}">{{ key }}</h2>
+<table style="width: 100%" class="indextable genindextable">
+  <tr>
+    {%- for entryname, (links, subitems, _) in entries %}
+    <li>
+      {{ indexentries(entryname, links) }} {%- if subitems %}
+      <ul>
+        {%- for subentryname, subentrylinks in subitems %}
+        <li>{{ indexentries(subentryname, subentrylinks) }}</li>
+        {%- endfor %}
+      </ul>
+      {%- endif -%}
+    </li>
+    {%- endfor %}
+  </tr>
+</table>
+{% endfor %} {% endblock %} {% block sidebarrel %} {% if split_index %}
+<h4>{{ _('Index') }}</h4>
+<p>
+  {% for key, dummy in genindexentries -%}
+  <a href="{{ pathto('genindex-' + key) }}"><strong>{{ key }}</strong></a>
+  {% if not loop.last %}| {% endif %} {%- endfor %}
+</p>
+
+<p>
+  <a href="{{ pathto('genindex-all') }}"
+    ><strong>{{ _('Full index on one page') }}</strong></a
+  >
+</p>
+{% endif %} {{ super() }} {% endblock %}
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
new file mode 100644
index 00000000..25d65cd5
--- /dev/null
+++ b/docs/_templates/layout.html
@@ -0,0 +1,4 @@
+{% extends "!layout.html" %} {% block menu %} {{ super() }}
+<a href="{{pathto('py-modindex.html', 1)}}">Module Index (API)</a>
+<a href="{{pathto('genindex.html', 1)}}">General Index</a>
+{% endblock %}
diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t
new file mode 100644
index 00000000..8ce1b5a1
--- /dev/null
+++ b/docs/_templates/module.rst_t
@@ -0,0 +1,8 @@
+{%- if show_headings and not separate %}
+{{ basename.split(".")[-1] | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
diff --git a/docs/_templates/package.rst_t b/docs/_templates/package.rst_t
new file mode 100644
index 00000000..d62bb941
--- /dev/null
+++ b/docs/_templates/package.rst_t
@@ -0,0 +1,44 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{{ pkgname.split(".")[-1] | e | heading }}
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if not modulefirst and not is_namespace %}
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if submodules or subpackages %}
+.. rubric:: Submodules and Subpackages
+{% endif %}
+
+{%- if subpackages %}
+
+{{ toctree(subpackages) }}
+{% endif %}
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{%- else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{% endif %}
diff --git a/docs/_templates/toc.rst_t b/docs/_templates/toc.rst_t
new file mode 100644
index 00000000..878540ce
--- /dev/null
+++ b/docs/_templates/toc.rst_t
@@ -0,0 +1,7 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
diff --git a/doc/analysis.rst b/docs/analysis.rst
similarity index 100%
rename from doc/analysis.rst
rename to docs/analysis.rst
diff --git a/doc/analysis/fit.rst b/docs/analysis/fit.rst
similarity index 100%
rename from doc/analysis/fit.rst
rename to docs/analysis/fit.rst
diff --git a/doc/analysis/statistics.rst b/docs/analysis/statistics.rst
similarity index 100%
rename from doc/analysis/statistics.rst
rename to docs/analysis/statistics.rst
diff --git a/doc/analysis/visualization.rst b/docs/analysis/visualization.rst
similarity index 100%
rename from doc/analysis/visualization.rst
rename to docs/analysis/visualization.rst
diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 00000000..4b3ede42
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,14 @@
+API
+===
+
+The PWA pages contains a few functions that can be used in the Jupyter
+notebooks that underlie these pages.
+
+.. toctree::
+
+  api/pwa_pages
+
+.. seealso::
+
+  * :ref:`modindex`
+  * :ref:`genindex`
diff --git a/doc/conf.py b/docs/conf.py
similarity index 59%
rename from doc/conf.py
rename to docs/conf.py
index 52d6ed11..8cf08833 100644
--- a/doc/conf.py
+++ b/docs/conf.py
@@ -7,54 +7,91 @@
 https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 
+import os
+import shutil
+import subprocess
 from typing import Dict
 
 from docutils import nodes
+from pkg_resources import get_distribution
 from sphinx.application import Sphinx
 
 # -- Project information -----------------------------------------------------
 project = "PWA Software Pages"
-copyright = "2020"
+copyright = "2020, ComPWA"
 author = "Common Partial Wave Analysis"
 
+__release = get_distribution("pwa_pages").version
+version = ".".join(__release.split(".")[:3])
+
+# -- Generate API skeleton ----------------------------------------------------
+shutil.rmtree("api", ignore_errors=True)
+subprocess.call(
+    " ".join(
+        [
+            "sphinx-apidoc",
+            "../src/pwa_pages/",
+            "-o api/",
+            "--force",
+            "--no-toc",
+            "--templatedir _templates",
+            "--separate",
+        ]
+    ),
+    shell=True,
+)
 
-# -- General configuration ---------------------------------------------------
 
-source_suffix = [
-    ".md",
-    ".rst",
-]
+# -- General configuration ---------------------------------------------------
+master_doc = "index.md"
+source_suffix = {
+    ".ipynb": "myst-nb",
+    ".md": "myst-nb",
+    ".rst": "restructuredtext",
+}
 
 # The master toctree document.
 master_doc = "index"
+modindex_common_prefix = [
+    "pwa_pages.",
+]
 
 extensions = [
-    "myst_parser",
-    "nbsphinx",
+    "myst_nb",
+    "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
+    "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
     "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
     "sphinx_copybutton",
-    "sphinx_math_dollar",
+    "sphinx_panels",
+    "sphinx_thebe",
     "sphinx_togglebutton",
     "sphinxcontrib.bibtex",
 ]
-mathjax_config = {
-    "tex2jax": {
-        "inlineMath": [["\\(", "\\)"]],
-        "displayMath": [["\\[", "\\]"]],
-    },
-}
-
 exclude_patterns = [
-    ".DS_Store",
-    "README.md",
-    "Thumbs.db",
-    "build",
+    "**.ipynb_checkpoints",
+    "*build",
+    "adr*",
+    "tests",
 ]
 
 # General sphinx settings
+add_module_names = False
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+    "special-members": ", ".join(
+        [
+            "__call__",
+            "__eq__",
+        ]
+    ),
+}
 html_copy_source = True  # needed for download notebook button
 html_show_copyright = False
 html_show_sourcelink = False
@@ -63,15 +100,25 @@
 html_theme = "sphinx_book_theme"
 html_theme_options = {
     "repository_url": "https://github.com/ComPWA/PWA-pages",
-    "repository_branch": "master",
-    "path_to_docs": "doc",
+    "repository_branch": "stable",
+    "path_to_docs": "docs",
     "use_edit_page_button": True,
     "use_issues_button": True,
     "use_repository_button": True,
+    "launch_buttons": {
+        "binderhub_url": "https://mybinder.org",
+        "colab_url": "https://colab.research.google.com",
+        "notebook_interface": "jupyterlab",
+        "thebe": True,
+        "thebelab": True,
+    },
     "expand_sections": ["theory"],
+    "theme_dev_mode": True,
 }
 html_title = "Partial Wave Analysis"
-todo_include_todos = True
+pygments_style = "sphinx"
+todo_include_todos = False
+viewcode_follow_imported_members = True
 
 # Cross-referencing configuration
 default_role = "py:obj"
@@ -79,41 +126,85 @@
 nitpicky = True  # warn if cross-references are missing
 nitpick_ignore = []
 
-# Settings for intersphinx
+# Intersphinx settings
 intersphinx_mapping = {
-    "ComPWA": ("https://pwa.readthedocs.io/projects/compwa/en/latest/", None),
+    "ComPWA": ("https://pwa.readthedocs.io/projects/compwa/en/latest", None),
     "expertsystem": (
-        "https://pwa.readthedocs.io/projects/expertsystem/en/stable/",
+        "https://pwa.readthedocs.io/projects/expertsystem/en/stable",
         None,
     ),
-    "numpy": ("https://numpy.org/doc/stable/", None),
+    "mypy": ("https://mypy.readthedocs.io/en/stable", None),
     "pycompwa": ("https://compwa.github.io", None),
-    "python": ("https://docs.python.org/3/", None),
+    "python": ("https://docs.python.org/3", None),
     "tensorwaves": (
-        "https://pwa.readthedocs.io/projects/tensorwaves/en/latest/",
+        "https://pwa.readthedocs.io/projects/tensorwaves/en/stable",
         None,
     ),
-    "tf_pwa": ("https://pwa.readthedocs.io/projects/tf-pwa/en/latest/", None),
-    "tox": ("https://tox.readthedocs.io/en/stable/", None),
+    "tf_pwa": ("https://pwa.readthedocs.io/projects/tf-pwa/en/latest", None),
+    "tox": ("https://tox.readthedocs.io/en/stable", None),
 }
 
 # Settings for autosectionlabel
 autosectionlabel_prefix_document = True
 
+# Settings for copybutton
+copybutton_prompt_is_regexp = True
+copybutton_prompt_text = r">>> |\.\.\. "  # doctest
+
 # Settings for linkcheck
 linkcheck_anchors = False
-linkcheck_ignore = []
+linkcheck_ignore = [
+    r"https://isbnsearch.org/isbn/\d+",
+]
+
+# Settings for myst_nb
+execution_timeout = -1
+jupyter_execute_notebooks = "force"
+nb_output_stderr = "remove"
+nb_render_priority = {
+    "html": (
+        "application/vnd.jupyter.widget-view+json",
+        "application/javascript",
+        "text/html",
+        "image/svg+xml",
+        "image/png",
+        "image/jpeg",
+        "text/markdown",
+        "text/latex",
+        "text/plain",
+    )
+}
+nb_render_priority["doctest"] = nb_render_priority["html"]
 
 # Settings for myst-parser
+myst_admonition_enable = True
 myst_update_mathjax = False
 
-# Settings for nbsphinx
-print("\033[93;1mWill run Jupyter notebooks!\033[0m")
-nbsphinx_execute = "always"
-nbsphinx_timeout = -1
-nbsphinx_execute_arguments = [
-    "--InlineBackend.figure_formats={'svg', 'pdf'}",
-]
+# Settings for Thebe cell output
+thebe_config = {
+    "repository_url": html_theme_options["repository_url"],
+    "repository_branch": html_theme_options["repository_branch"],
+}
+
+# -- Visualize dependencies ---------------------------------------------------
+if "READTHEDOCS" in os.environ or "GITHUB_WORKFLOW" in os.environ:
+    print("Generating module dependency tree...")
+    subprocess.call(
+        " ".join(
+            [
+                "HOME=.",  # in case of calling through tox
+                "pydeps",
+                "../src/pwa_pages",
+                "--exclude *._*",  # hide private modules
+                "--max-bacon=2",  # hide external dependency submodules
+                "--noshow",
+            ]
+        ),
+        shell=True,
+    )
+    if os.path.exists("pwa_pages.svg"):
+        with open("api/pwa_pages.rst", "a") as stream:
+            stream.write("\n.. image:: /pwa_pages.svg")
 
 # Add roles to simplify external linnks
 def setup(app: Sphinx):
diff --git a/docs/develop.rst b/docs/develop.rst
new file mode 100644
index 00000000..343d9798
--- /dev/null
+++ b/docs/develop.rst
@@ -0,0 +1,333 @@
+.. cSpell:ignore aquirdturtle docnb htmlcov ijmbarr labextension pylintrc
+.. cSpell:ignore ryantam serverextension testenv
+
+Develop
+=======
+
+.. list-table::
+
+  * - .. image:: https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod
+        :alt: GitPod
+        :align: left
+        :target: https://gitpod.io/#https://github.com/ComPWA/PWA-pages
+
+If you have installed the `pwa_pages` in :ref:`install:Editable mode`, it is
+easy to tweak the source code and try out new ideas immediately, because the
+source code is considered the 'installation'.
+
+.. admonition:: Conda and VSCode
+  :class: dropdown
+
+  The easiest way to , is by using :ref:`Conda <install:Step 2: Create a
+  virtual environment>` and :ref:`develop:Visual Studio code`. In that case,
+  the complete developer install procedure becomes:
+
+  .. code-block:: shell
+
+    git clone https://github.com/ComPWA/PWA-pages.git
+    cd PWA-pages
+    conda env create
+    conda activate es
+    pip install -e .[dev]
+    code .  # open folder in VSCode
+
+  For more info, see :ref:`develop:Visual Studio code`.
+
+
+Automated style checks
+----------------------
+
+When working on the source code of the `pwa_pages`, it is highly recommended to
+install certain additional Python tools. Assuming you installed the `pwa_pages`
+in :ref:`editable mode <install:Editable mode>`, these additional tools can be
+installed into your :ref:`virtual environment <install:Step 2: Create a virtual
+environment>` in one go:
+
+.. code-block:: shell
+
+  pip install -e .[dev]
+
+Most of the tools that are installed with this command use specific
+configuration files (e.g. `pyproject.toml
+<https://github.com/ComPWA/PWA-pages/blob/master/pyproject.toml>`_ for `black
+<https://black.readthedocs.io/>`_, `.pylintrc
+<https://github.com/ComPWA/PWA-pages/blob/master/.pylintrc>`_ for `pylint
+<http://pylint.pycqa.org/en/latest/>`_, and `tox.ini
+<https://github.com/ComPWA/PWA-pages/blob/master/tox.ini>`__ for `flake8
+<https://flake8.pycqa.org/>`_ and `pydocstyle <http://www.pydocstyle.org/>`_).
+These config files **define our convention policies**, such as :pep:`8`. If you
+run into persistent linting errors, this may mean we need to further specify
+our conventions. In that case, it's best to create an issue and propose a
+policy change that can then be formulated in the config files.
+
+.. tip::
+  :class: dropdown
+
+  If you have Node.js (:code:`npm`) on your system, you can run a few
+  additional checks. Install these packages as follows (possibly with
+  administrator rights):
+
+  .. code-block:: bash
+
+    npm install -g cspell markdownlint-cli pyright
+
+  Normally, these packages are only run in the :ref:`CI <develop:Continuous
+  Integration>`, but if you have them installed, they are also run when you run
+  :ref:`tox <develop:Testing>` (local CI).
+
+  Note that :code:`pyright` requires Node.js v12.x (see install instructions
+  `here <https://nodejs.org/en/download/package-manager>`__).
+
+
+Pre-commit
+----------
+
+All **style checks** are enforced through a tool called `pre-commit
+<https://pre-commit.com/>`__. This tool needs to be activated, but only once,
+after you clone the repository:
+
+.. code-block:: shell
+
+  pre-commit install
+
+Upon committing, :code:`pre-commit` now runs a set of checks as defined in the
+file `.pre-commit-config.yaml
+<https://github.com/ComPWA/PWA-pages/blob/master/.pre-commit-config.yaml>`_
+over all staged files. You can also quickly run all checks over *all* indexed
+files in the repository with the command:
+
+.. code-block:: shell
+
+  pre-commit run -a
+
+This command is also run on GitHub actions whenever you submit a pull request,
+ensuring that all files in the repository follow the conventions set in the
+config files of these tools.
+
+
+Documentation
+-------------
+
+The documentation that you find on `pwa.rtfd.io <http://pwa.rtfd.io>`_ are
+built from the `documentation source code folder
+<https://github.com/ComPWA/PWA-pages/tree/master/docs>`_ (:file:`docs`) with
+`Sphinx <https://www.sphinx-doc.org>`_. Sphinx also `builds the API
+<https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html>`_ and therefore
+checks whether the `docstrings <https://www.python.org/dev/peps/pep-0257/>`_ in
+the Python source code are valid and correctly interlinked.
+
+You can quickly build the documentation from the root directory of this
+repository with the command:
+
+.. code-block:: shell
+
+  tox -e doc
+
+Alternatively, you can run :code:`sphinx-build` yourself as follows:
+
+.. code-block:: shell
+
+  cd docs
+  make html  # or EXECUTE_NB= make html
+
+A nice feature of `Read the Docs <https://readthedocs.org/>`_, where we host
+our documentation, is that documentation is built for each pull request as
+well. This means that you can view the documentation for your changes as well.
+For more info, see `here
+<https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html>`__,
+or just click "details" under the RTD check once you submit your PR.
+
+We make use of `Markedly Structured Text <https://myst-parser.readthedocs.io>`_
+(MyST), so you can write the documentation in either `reStructuredText
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ or
+`Markdown <https://www.markdownguide.org>`_. In addition, it's easy to write
+(interactive) code examples in Jupyter notebooks and host them on the website,
+(see `MyST-NB <https://myst-nb.readthedocs.io>`_)!
+
+
+Jupyter Notebooks
+-----------------
+
+.. margin::
+
+  .. tip::
+    Sometimes it happens that your Jupyter installation does not recognize your
+    :ref:`virtual environment <install:Step 2: Create a virtual environment>`.
+    In that case, have a look at `these instructions
+    <https://ipython.readthedocs.io/en/stable/install/kernel_install.html#kernels-for-different-environments>`__.
+
+The `docs <https://github.com/ComPWA/PWA-pages/tree/master/docs>`_ folder
+contains a few Jupyter notebooks. These notebooks are run and tested whenever
+you make a :ref:`pull request <develop:Git and GitHub>`. If you want to improve
+those notebooks, we recommend working with `Jupyter Lab
+<https://jupyterlab.readthedocs.io/en/stable/>`_, which is installed with the
+:code:`dev` requirements of the `pwa_pages`. Jupyter Lab offers a nicer
+developer experience than the default Jupyter notebook editor does. In
+addition, we recommend to install a few extensions:
+
+.. code-block:: shell
+
+  jupyter labextension install jupyterlab-execute-time
+  jupyter labextension install @ijmbarr/jupyterlab_spellchecker
+  jupyter labextension install @aquirdturtle/collapsible_headings
+  jupyter labextension install @ryantam626/jupyterlab_code_formatter
+  jupyter labextension install @jupyter-widgets/jupyterlab-manager
+
+  jupyter serverextension enable --py jupyterlab_code_formatter
+
+Now, if you want to test all notebooks documentation folder and check how they
+will look like in the :ref:`develop:Documentation`, you can do this with:
+
+.. code-block:: shell
+
+  tox -e docnb
+
+This command takes more time than :code:`tox -e doc`, but it is good practice
+to do this before you submit a pull request.
+
+
+Spelling
+--------
+
+Throughout this repository, we follow American English (`en-us
+<https://www.andiamo.co.uk/resources/iso-language-codes/>`_) spelling
+conventions. As a tool, we use `cSpell
+<https://github.com/streetsidesoftware/cspell/blob/master/packages/cspell/README.md>`_
+because it allows to check variable names in camel case and snake case.  This
+way, a spelling checker helps you in avoid mistakes in the code as well!
+
+Accepted words are tracked through the :file:`cspell.json` file. As with the
+other config files, :file:`cspell.json` formulates our conventions with regard
+to spelling and can be continuously updated while our code base develops. In
+the file, the :code:`words` section lists words that you want to see as
+suggested corrections, while :code:`ignoreWords` are just the words that won't
+be flagged. Try to be sparse in adding words: if some word is just specific to
+one file, you can `ignore it inline
+<https://www.npmjs.com/package/cspell#ignore>`_, or you can add the file to the
+:code:`ignorePaths` section if you want to ignore it completely.
+
+It is easiest to use cSpell in :ref:`develop:Visual Studio Code`, through
+the `Code Spell Checker
+<https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker>`_
+extension: it provides linting, suggests corrections from the :code:`words`
+section, and enables you to quickly add or ignore words through the
+:file:`cspell.json` file. Alternatively, you can `run cSpell
+<https://www.npmjs.com/package/cspell#installation>`__ on the entire code base
+(with :code:`cspell $(git ls-files)`), but for that your system requires `npm
+<https://www.npmjs.com/>`_.
+
+
+Git and GitHub
+--------------
+
+The `pwa_pages` source code is maintained with Git and published through
+GitHub. We keep track of issues with the code, documentation, and developer
+set-up with GitHub issues (see overview `here
+<https://github.com/ComPWA/PWA-pages/issues>`__). This is also the place where
+you can `report bugs <https://github.com/ComPWA/PWA-pages/issues/new/choose>`_.
+
+
+Issue management
+^^^^^^^^^^^^^^^^
+
+We keep track of issue dependencies, time estimates, planning, pipeline
+statuses, et cetera with `ZenHub <https://app.zenhub.com>`_. You can use your
+GitHub account to log in there and automatically get access to the `pwa_pages`
+issue board once you are part of the `ComPWA organization
+<https://github.com/ComPWA>`_.
+
+Publicly available are:
+
+* `Issue labels <https://github.com/ComPWA/PWA-pages/labels>`_: help to
+  categorize issues by type (maintenance, enhancement, bug, etc.).
+
+* `Milestones
+  <https://github.com/ComPWA/PWA-pages/milestones?direction=asc&sort=title&state=open>`__:
+  way to bundle issues for upcoming releases.
+
+
+Commit conventions
+^^^^^^^^^^^^^^^^^^
+
+* Please use
+  `conventional commit messages <https://www.conventionalcommits.org/>`_: start
+  the commit with a semantic keyword (see e.g. `Angular
+  <https://github.com/angular/angular/blob/master/CONTRIBUTING.md#type>`_ or
+  `these examples <https://seesparkbox.com/foundry/semantic_commit_messages>`_,
+  followed by `a column <https://git-scm.com/docs/git-interpret-trailers>`_,
+  then the message. The message itself should be in imperative mood — just
+  imagine the commit to give a command to the code framework. So for instance:
+  :code:`feat: add coverage report tools` or :code:`fix: remove ...`.
+
+* Keep pull requests small. If the issue you try to address is too big, discuss
+  in the team whether the issue can be converted into an `Epic
+  <https://blog.zenhub.com/working-with-epics-in-github>`_ and split up into
+  smaller tasks.
+
+* Before creating a pull request, run :code:`tox`. See also
+  :ref:`develop:Testing`.
+
+* Also use a
+  `conventional commit message <https://www.conventionalcommits.org/>`_ style
+  for the PR title. This is because we follow a `linear commit history
+  <https://docs.github.com/en/github/administering-a-repository/requiring-a-linear-commit-history>`_
+  and the PR title will become the eventual commit message. Note that a
+  conventional commit message style is `enforced through GitHub Actions
+  <https://github.com/ComPWA/PWA-pages/actions?query=workflow%3A%22PR+linting%22>`_,
+  as well as :ref:`PR labels <develop:Issue management>`.
+
+* PRs can only be merged through 'squash and merge'. There, you will see a
+  summary based on the separate commits that constitute this PR. Leave the
+  relevant commits in as bullet points. See the `commit history
+  <https://github.com/ComPWA/PWA-pages/commits/master>`_ for examples. This
+  comes in especially handy when :ref:`drafting a release <develop:Milestones
+  and releases>`!
+
+
+Milestones and releases
+^^^^^^^^^^^^^^^^^^^^^^^
+
+An overview of the `pwa_pages` releases can be found on the `release page
+<https://github.com/ComPWA/PWA-pages/releases>`__.
+
+Release notes are automatically generated from the PRs that were merged into
+the master branch since the previous tag (see `latest draft
+<https://github.com/ComPWA/PWA-pages/releases>`_). The changelog there is
+generated from the PR titles and categorized by issue label. New releases are
+automatically published to PyPI when a new tag with such release notes is
+created (see `setuptools-scm <https://pypi.org/project/setuptools-scm>`_).
+
+
+Continuous Integration
+^^^^^^^^^^^^^^^^^^^^^^
+
+All :ref:`style checks <develop:Automated style checks>`, testing of the
+:ref:`documentation and links <develop:Documentation>`, and :ref:`unit tests
+<develop:Testing>` are performed upon each pull request through `GitHub Actions
+<https://docs.github.com/en/actions>`_ (see status overview `here
+<https://github.com/ComPWA/PWA-pages/actions>`__). All checks performed for
+each PR have to pass before the PR can be merged.
+
+
+Visual Studio code
+------------------
+
+We recommend using `Visual Studio Code <https://code.visualstudio.com/>`_ as
+it's free, regularly updated, and very flexible through it's wide offer of user
+extensions.
+
+If you add or open this repository as a `VSCode workspace
+<https://code.visualstudio.com/docs/editor/multi-root-workspaces>`_, the file
+`.vscode/settings.json
+<https://github.com/ComPWA/PWA-pages/blob/master/.vscode/settings.json>`_ will
+ensure that you have the right developer settings for this repository. In
+addition, VSCode will automatically recommend you to install a number of
+extensions that we use when working on this code base (they are `defined
+<https://code.visualstudio.com/updates/v1_6#_workspace-extension-recommendations>`__
+in the `.vscode/extensions.json
+<https://github.com/ComPWA/PWA-pages/blob/master/.vscode/extensions.json>`_
+file).
+
+You can still specify your own settings in `either the user or encompassing
+workspace settings <https://code.visualstudio.com/docs/getstarted/settings>`_,
+as the VSCode settings that come with this are folder settings.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..30c01f35
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,75 @@
+# PWA Software Pages
+
+```{title} Welcome
+
+```
+
+<!-- prettier:disable -->
+
+```{eval-rst}
+.. list-table::
+  :widths: auto
+  :align: left
+
+  * - .. image:: https://img.shields.io/badge/License-GPLv3+-blue.svg
+        :alt: GPLv3+ license
+        :target: https://www.gnu.org/licenses/gpl-3.0-standalone.html
+    - .. image:: https://readthedocs.org/projects/pwa/badge/?version=latest
+        :alt: Documentation build status
+        :target: https://pwa.readthedocs.io
+```
+
+<!-- prettier:enable -->
+
+```{warning}
+These pages and are **under development**.
+```
+
+The PWA Software Pages serve two purposes:
+
+1. They aim to bring together the many Partial Wave Analysis frameworks out
+   there on the market through interlinked documentation.
+
+2. They provide a dynamic platform to collect and maintain knowledge on both
+   PWA theory and software tools.
+
+As such, the pages consist three main components: [theory](./theory.rst),
+[analysis techniques](./analysis.rst), and [software](./software.rst). The
+[theory pages](./theory.rst) are to be a collection of the basics of PWA
+theory, along with references to more in-depth sources. This is useful, because
+it is often difficult for newcomers to find their way around in the growing
+amount of PWA literature and experimental results. The
+[analysis section](./analysis.rst) visits some of the common statistics
+techniques that you need to be familiar with to do PWA (and event selection
+more generally). The [software pages](./software.rst) serve as a guide through
+the available software tools that are relevant to PWA software development.
+
+```{toctree}
+---
+maxdepth: 2
+---
+theory
+analysis
+software
+develop
+```
+
+- {ref}`Python API <modindex>`
+
+```{toctree}
+---
+hidden:
+---
+api
+```
+
+```{toctree}
+---
+caption: Related projects
+hidden:
+---
+PWA Expert System <http://expertsystem.rtfd.io>
+TensorWaves <http://tensorwaves.rtfd.io>
+TF-PWA <http://tf-pwa.rtfd.io>
+pycompwa <https://compwa.github.io>
+```
diff --git a/doc/software.rst b/docs/software.rst
similarity index 100%
rename from doc/software.rst
rename to docs/software.rst
diff --git a/doc/software/documentation.rst b/docs/software/documentation.rst
similarity index 100%
rename from doc/software/documentation.rst
rename to docs/software/documentation.rst
diff --git a/doc/software/git.rst b/docs/software/git.rst
similarity index 100%
rename from doc/software/git.rst
rename to docs/software/git.rst
diff --git a/doc/software/git/branching.rst b/docs/software/git/branching.rst
similarity index 100%
rename from doc/software/git/branching.rst
rename to docs/software/git/branching.rst
diff --git a/doc/software/git/commit.rst b/docs/software/git/commit.rst
similarity index 100%
rename from doc/software/git/commit.rst
rename to docs/software/git/commit.rst
diff --git a/doc/software/git/github.rst b/docs/software/git/github.rst
similarity index 100%
rename from doc/software/git/github.rst
rename to docs/software/git/github.rst
diff --git a/doc/software/git/remotes.rst b/docs/software/git/remotes.rst
similarity index 100%
rename from doc/software/git/remotes.rst
rename to docs/software/git/remotes.rst
diff --git a/doc/software/python.rst b/docs/software/python.rst
similarity index 100%
rename from doc/software/python.rst
rename to docs/software/python.rst
diff --git a/doc/software/testing.rst b/docs/software/testing.rst
similarity index 100%
rename from doc/software/testing.rst
rename to docs/software/testing.rst
diff --git a/doc/software/tips.rst b/docs/software/tips.rst
similarity index 100%
rename from doc/software/tips.rst
rename to docs/software/tips.rst
diff --git a/doc/theory.rst b/docs/theory.rst
similarity index 100%
rename from doc/theory.rst
rename to docs/theory.rst
diff --git a/doc/theory/bibliography.bib b/docs/theory/bibliography.bib
similarity index 100%
rename from doc/theory/bibliography.bib
rename to docs/theory/bibliography.bib
diff --git a/doc/theory/data.rst b/docs/theory/data.md
similarity index 70%
rename from doc/theory/data.rst
rename to docs/theory/data.md
index 2ee38ed5..88402db4 100644
--- a/doc/theory/data.rst
+++ b/docs/theory/data.md
@@ -1,16 +1,14 @@
-Experimental data
-=================
+# Experimental data
 
-.. warning::
-  These pages and are **under development**.
+```{warning}
+These pages and are **under development**.
+```
 
-Types of experiments
---------------------
+## Types of experiments
 
 - Formation vs production
 
-PWA data
---------
+## PWA data
 
 - Why are momentum tuples sufficient?
 - How to determine initial 4-momentum?
@@ -21,8 +19,7 @@ PWA data
   - Branching fraction
   - (?) Fit fractions
 
-Comparison with Measurements
-----------------------------
+## Comparison with Measurements
 
 Luminosity $L$
 
@@ -30,9 +27,9 @@ Measurements $N$
 
 Cross section $\sigma$
 
-.. math::
-
-  \frac{dN}{d\Phi_f} = L \cdot \frac{d\sigma}{d\Phi_f}
+$$
+\frac{dN}{d\Phi_f} = L \cdot \frac{d\sigma}{d\Phi_f}
+$$
 
 Number of events in a infinitesimal phase space element $\Phi_f$ is
 proportional to the cross section of a initial state transitioning to the final
diff --git a/doc/theory/dynamics.ipynb b/docs/theory/dynamics.ipynb
similarity index 66%
rename from doc/theory/dynamics.ipynb
rename to docs/theory/dynamics.ipynb
index 5c9653ad..7c078363 100644
--- a/doc/theory/dynamics.ipynb
+++ b/docs/theory/dynamics.ipynb
@@ -8,13 +8,12 @@
    ]
   },
   {
-   "cell_type": "raw",
-   "metadata": {
-    "raw_mimetype": "text/restructuredtext"
-   },
+   "cell_type": "markdown",
+   "metadata": {},
    "source": [
-    ".. warning::\n",
-    "  These pages and are **under development**."
+    "```{warning}\n",
+    "These pages and are **under development**.\n",
+    "```"
    ]
   },
   {
@@ -25,31 +24,37 @@
    ]
   },
   {
-   "cell_type": "raw",
-   "metadata": {
-    "raw_mimetype": "text/restructuredtext"
-   },
+   "cell_type": "markdown",
+   "metadata": {},
    "source": [
-    "Since :term:`scattering operator` ($S$-matrix) formulates the transition amplitude from initial state :math:`\\left|i\\right>` to final state :math:`\\left|f\\right>` through :math:`\\left<i\\right|S\\left|f\\right>`, it is a **unitary** operator—probability is conserved, meaning $SS^* = I$. Now, :ref:`having defined the transition operator <theory/introduction:Transition amplitude>` through $S = I + iT$, we can introduce another operator: $K^{-1} = T^{-1} + iI$ :cite:`chungPartialWaveAnalysis1995`. \n",
+    "Since {term}`scattering operator` ($S$-matrix) formulates the transition amplitude from initial state $\\left|i\\right>$ to final state $\\left|f\\right>$ through $\\left<i\\right|S\\left|f\\right>$, it is a **unitary** operator—probability is conserved, meaning $SS^* = I$. Now, {ref}`having defined the transition operator <theory/introduction:Transition amplitude>` through $S = I + iT$, we can introduce another operator: $K^{-1} = T^{-1} + iI$ {cite}`chungPartialWaveAnalysis1995`. \n",
     "  \n"
    ]
   },
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
    "metadata": {
-    "raw_mimetype": "text/restructuredtext"
+    "jupyter": {
+     "source_hidden": true
+    }
    },
    "source": [
-    ".. todo:: Explain why this new matrix interesting?"
+    "```{todo}\n",
+    "Explain why this new matrix interesting?\n",
+    "```"
    ]
   },
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
    "metadata": {
-    "raw_mimetype": "text/restructuredtext"
+    "jupyter": {
+     "source_hidden": true
+    }
    },
    "source": [
-    ".. todo:: Definition in terms of $T$-matrix"
+    "```{todo}\n",
+    "Definition in terms of $T$-matrix\n",
+    "```"
    ]
   },
   {
@@ -67,12 +72,16 @@
    ]
   },
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
    "metadata": {
-    "raw_mimetype": "text/restructuredtext"
+    "jupyter": {
+     "source_hidden": true
+    }
    },
    "source": [
-    ".. todo:: Derive from $K$-matrix instead/as well."
+    "```{todo}\n",
+    "Derive from $K$-matrix instead/as well.\n",
+    "```"
    ]
   },
   {
@@ -102,27 +111,14 @@
     "E' = E_0 - \\frac{i}{2}\\Gamma\n",
     "$$\n",
     "\n",
-    "Now, as an experimental physicist, one is interested in predicting the probability of observing the particle at energy $E$ (we want to describe the observed invariant mass distributions). This can be achieved by applying a [Fourier transform](https://en.wikipedia.org/wiki/Fourier_transform), so that $\\psi$ is described in terms of energy $E$ (or frequency $\\omega$) instead of time $t$:"
-   ]
-  },
-  {
-   "cell_type": "raw",
-   "metadata": {
-    "raw_mimetype": "text/restructuredtext"
-   },
-   "source": [
-    ".. math::\n",
+    "Now, as an experimental physicist, one is interested in predicting the probability of observing the particle at energy $E$ (we want to describe the observed invariant mass distributions). This can be achieved by applying a [Fourier transform](https://en.wikipedia.org/wiki/Fourier_transform), so that $\\psi$ is described in terms of energy $E$ (or frequency $\\omega$) instead of time $t$:\n",
     "\n",
-    "  \\psi(E)\n",
-    "  & \\propto \\psi_0 \\int_0^\\infty e^{i\\left(E-E_0+\\tfrac{i}{2}\\Gamma\\right)t}\\,\\mathrm{d}t\n",
+    "$$\n",
+    "\\psi(E)\n",
+    "\\propto \\psi_0 \\int_0^\\infty e^{i\\left(E-E_0+\\tfrac{i}{2}\\Gamma\\right)t}\\,\\mathrm{d}t\n",
+    "\\propto \\frac{1}{\\left(E-E_0\\right) - \\tfrac{i}{2}\\Gamma}\n",
+    "$$\n",
     "\n",
-    "  & \\propto \\frac{1}{\\left(E-E_0\\right) - \\tfrac{i}{2}\\Gamma}"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
     "The probability to observe the particle at energy $E$ is therefore:\n",
     "\n",
     "$$\n",
@@ -132,13 +128,16 @@
    ]
   },
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
    "metadata": {
-    "raw_mimetype": "text/restructuredtext"
+    "jupyter": {
+     "source_hidden": true
+    }
    },
    "source": [
-    ".. todo::\n",
-    "    Describe relation between $\\psi(E)$ and transition amplitude $M$"
+    "```{todo}\n",
+    "Describe relation between $\\psi(E)$ and transition amplitude $M$\n",
+    "```"
    ]
   },
   {
@@ -166,27 +165,32 @@
    ]
   },
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
    "metadata": {
-    "raw_mimetype": "text/restructuredtext"
+    "jupyter": {
+     "source_hidden": true
+    }
    },
    "source": [
-    ".. todo::\n",
-    "\n",
-    "  Describe how the **relativistic Breit-Wigner formula**:\n",
+    "```{todo}\n",
+    "Describe how the **relativistic Breit-Wigner formula**:\n",
     "\n",
-    "  .. math::\n",
-    "\n",
-    "    M(E) \\propto\n",
-    "    \\frac{m_0\\Gamma}{m_0^2 - m_{ab}^2 - im_0\\Gamma}\n",
+    "$$\n",
+    "M(E) \\propto \\frac{m_0\\Gamma}{m_0^2 - m_{ab}^2 - im_0\\Gamma}\n",
+    "$$\n",
     "\n",
-    "  is derived and why this is important in case of $\\Gamma \\gg m_0$."
+    "is derived and why this is important in case of $\\Gamma \\gg m_0$.\n",
+    "```"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "hide-input"
+    ]
+   },
    "outputs": [],
    "source": [
     "from pwa_pages import plot\n",
@@ -196,7 +200,7 @@
     "gamma2_4 = Gamma ** 2 / 4\n",
     "plot(\n",
     "    lambda x: gamma2_4 / ((x - E0) ** 2 + gamma2_4),\n",
-    "    range=(0, 1.5),\n",
+    "    plot_range=(0, 1.5),\n",
     "    title=\"Non-relativistic Breit-Wigner\",\n",
     "    xlabel=\"$E$ (A.U.)\",\n",
     "    ylabel=\"$|M(E)|^2$\",\n",
diff --git a/docs/theory/formalisms.md b/docs/theory/formalisms.md
new file mode 100644
index 00000000..a600da08
--- /dev/null
+++ b/docs/theory/formalisms.md
@@ -0,0 +1,88 @@
+# Formalisms
+
+```{warning}
+These pages and are **under development**.
+```
+
+## Helicity Formalism
+
+- Lorentz-invariance of helicity operator
+
+- Types
+
+  - Two-body decay amplitude
+  - Sequential two-body decay amplitude
+
+- Definition of angles
+
+  - Production angle
+  - Helicity angle
+  - Treiman-Yang angle
+  - Overview of kinematic variables
+
+- Dynamics:
+
+  - Wigner-D functions
+  - Clebsch-Gordan coefficients
+
+- Kinematic variables
+- An example
+
+.. admonition:: The old text :class: dropdown
+
+Two particle states are the key element here. With these one can construct
+states of total spin $J$ and projection $M$.
+
+The probability amplitude of a state with spin J and projection M decaying into
+two particles 1 and 2 with helicities $\lambda_i$ and momentum $\vec{p}$ in the
+cms frame is given by {cite}`chungSpinFormalismsUpdated2014`, p.16.
+
+$$
+two body decay amplitude here
+$$
+
+In the helicity formalism sequential two body decays are easy to handle
+
+$$
+seq two body decay amplitude here
+$$
+
+Then show explicitly what ComPWA implements and which components correspond to
+what part in the equation. So we would refer in the Doxygen docs to
+
+- the Wigner D functions
+
+- the Kinematics class
+
+- the IntensityBuilderXML with the two functions createSequentialAmplitudeFT
+  createHelicityDecayFT
+
+- the dynamical functions
+
+- the phase space element calculations?
+
+[IntensityBuilderXML](https://compwa.github.io/ComPWA/classComPWA_1_1Physics_1_1IntensityBuilderXML.html)
+
+## Canonical Formalism
+
+.. admonition:: The old text :class: dropdown
+
+The canonical formalism gives access to the orbital angular momentum $L$ and
+the coupled Spin $S$ arising from a two particle state.
+
+There is a simple connection between the two formalism. Show that here
+
+This expression is simply inserted into equation () and that is it!
+
+The choice of the formalism depends on the physics process being analyzed. Give
+an example here.
+
+## Lorentz-invariant Formalisms
+
+### Rarita-Schwinger
+
+## Other Spin Formalisms
+
+### (Covariant) Tensor Formalisms
+
+### Spin-projection formalisms
diff --git a/doc/theory/glossary.rst b/docs/theory/glossary.rst
similarity index 100%
rename from doc/theory/glossary.rst
rename to docs/theory/glossary.rst
diff --git a/doc/theory/introduction.rst b/docs/theory/introduction.rst
similarity index 100%
rename from doc/theory/introduction.rst
rename to docs/theory/introduction.rst
diff --git a/doc/theory/results.rst b/docs/theory/results.rst
similarity index 100%
rename from doc/theory/results.rst
rename to docs/theory/results.rst
diff --git a/doc/theory/topics.rst b/docs/theory/topics.rst
similarity index 100%
rename from doc/theory/topics.rst
rename to docs/theory/topics.rst
diff --git a/doc/theory/topics/cqm.rst b/docs/theory/topics/cqm.rst
similarity index 100%
rename from doc/theory/topics/cqm.rst
rename to docs/theory/topics/cqm.rst
diff --git a/doc/theory/topics/sm.rst b/docs/theory/topics/sm.rst
similarity index 100%
rename from doc/theory/topics/sm.rst
rename to docs/theory/topics/sm.rst
diff --git a/doc/theory/z.references.rst b/docs/theory/z.references.rst
similarity index 100%
rename from doc/theory/z.references.rst
rename to docs/theory/z.references.rst
diff --git a/environment.yml b/environment.yml
index 71863434..b65aa5d4 100644
--- a/environment.yml
+++ b/environment.yml
@@ -1,9 +1,9 @@
 name: pwa-pages
 channels:
   - defaults
-  - conda-forge
 dependencies:
   - python>=3.6
   - pip
+  - graphviz # for binder
   - pip:
       - -e .[dev]
diff --git a/pyproject.toml b/pyproject.toml
index 88796793..10639bb9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,17 +1,16 @@
 [build-system]
 requires = [
-    "setuptools>=30.3.0",
+    "setuptools>=36.2.1", # environment markers
     "setuptools_scm",
     "wheel",
 ]
 
 [tool.setuptools_scm]
-write_to = "version.py"
+write_to = "pwa_pages/version.py"
 
 [tool.black]
 line-length = 79
 target-version = [
-    'py35',
     'py36',
     'py37',
     'py38',
@@ -33,5 +32,5 @@ exclude = '''
 
 [tool.isort]
 profile = "black"
-src_paths = ["doc/pwa_pages"]
+src_paths = ["src", "tests"]
 line_length = 79
diff --git a/pyrightconfig.json b/pyrightconfig.json
index 8c232123..0036b13f 100644
--- a/pyrightconfig.json
+++ b/pyrightconfig.json
@@ -1,6 +1,6 @@
 {
   "exclude": [".git", ".tox"],
-  "include": ["doc", "setup.py"],
+  "include": ["docs", "src", "tests"],
   "reportGeneralTypeIssues": false,
   "reportUnboundVariable": false,
   "reportUnusedClass": true,
diff --git a/setup.cfg b/setup.cfg
index bb800162..50c63050 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -2,11 +2,11 @@
 name = PWA-pages
 long_description = file: README.md
 long_description_content_type = text/markdown
-url = https://github.com/ComPWA/PWA-pages
 project_urls =
+    Tracker = https://github.com/ComPWA/PWA-pages/issues
+    Changelog = https://github.com/ComPWA/PWA-pages/releases
     Documentation = http://pwa.rtfd.io
     Source = https://github.com/ComPWA/PWA-pages
-    Tracker = https://github.com/ComPWA/PWA-pages/issues
 license = GPLv3 or later
 keywords =
     HEP
@@ -41,12 +41,10 @@ install_requires =
     numpy==1.19.2
 packages = find:
 package_dir =
-    =doc
+    =src
 
 [options.packages.find]
-where = doc
-include =
-    pwa_pages
+where = src
 
 [options.package_data]
 pwa_pages =
@@ -54,32 +52,41 @@ pwa_pages =
 
 [options.extras_require]
 doc =
+    graphviz==0.14.2
+    ipywidgets==7.5.1
     jupyter==1.0.0
-    myst-parser==0.12.10
-    nbsphinx==0.8.0
+    myst-nb==0.10.1
     pybtex==0.23.0
+    pydeps==1.9.11
     Sphinx==3.2.1
-    sphinx-book-theme==0.0.36
-    sphinx-copybutton==0.3.0
-    sphinx-math-dollar==1.2
-    sphinx-togglebutton==0.2.2
+    sphinx-book-theme==0.0.38
+    sphinx-copybutton==0.3.1
+    sphinx-panels==0.5.2
+    sphinx-thebe==0.0.8
+    sphinx-togglebutton==0.2.3
     sphinxcontrib-bibtex==1.0.0
 dev =
     %(doc)s
     black==20.8b1
     data-science-types==0.2.19
     doc8==0.8.1
-    flake8==3.8.4
-    isort==5.6.4
-    jupyterlab==2.2.8
-    jupyterlab-code-formatter==1.3.6
+    flake8==3.8.3 # >=3 for per-file-ignores
+    flake8-blind-except==0.1.1
+    flake8-bugbear==20.1.4
+    flake8-builtins==1.5.3
+    flake8-rst-docstrings==0.0.13
+    isort==5.6.1
+    jupyterlab==2.2.4
+    jupyterlab_code_formatter==1.3.6
+    jupyter_nbextensions_configurator==0.4.1
     labels==20.1.0
-    mypy==0.790
+    mypy==0.782
+    pep8-naming==0.11.1
     pre-commit==2.7.1
     pydocstyle==5.1.1
     pylint==2.6.0
     rstcheck==3.3.1
-    tox==3.20.1
+    tox==3.20.0
 
 [doc8]
 extension=.inc
@@ -107,6 +114,10 @@ ignore_missing_imports = True
 ignore_directives =
     bibliography,
     margin,
+    seealso,
+    sidebar,
+    tabbed,
+    thebe-button,
     toggle,
 ignore_roles =
     cite,
diff --git a/setup.py b/setup.py
index caca1c7f..e8b5ef2e 100644
--- a/setup.py
+++ b/setup.py
@@ -2,4 +2,7 @@
 
 from setuptools import setup
 
-setup(use_scm_version=True)
+setup(
+    use_scm_version=True,
+    setup_requires=["setuptools_scm"],
+)
diff --git a/doc/pwa_pages/__init__.py b/src/pwa_pages/__init__.py
similarity index 87%
rename from doc/pwa_pages/__init__.py
rename to src/pwa_pages/__init__.py
index 0bcf8762..0134072f 100644
--- a/doc/pwa_pages/__init__.py
+++ b/src/pwa_pages/__init__.py
@@ -8,12 +8,12 @@
 
 def plot(
     function: Callable[[SupportsFloat], Sequence[float]],
-    range: Tuple[float, float],  # pylint: disable=redefined-builtin
+    plot_range: Tuple[float, float],  # pylint: disable=redefined-builtin
     title: Optional[str] = None,
     xlabel: Optional[str] = None,
     ylabel: Optional[str] = None,
 ) -> None:
-    x_1, x_2 = range
+    x_1, x_2 = plot_range
     n_steps = 100
     x_values = np.linspace(x_1, x_2, n_steps)
     y_values = function(x_values)
diff --git a/doc/pwa_pages/py.typed b/src/pwa_pages/py.typed
similarity index 100%
rename from doc/pwa_pages/py.typed
rename to src/pwa_pages/py.typed
diff --git a/tox.ini b/tox.ini
index 51a35554..c8c5bc32 100644
--- a/tox.ini
+++ b/tox.ini
@@ -10,6 +10,7 @@ envlist =
 [testenv:doc]
 description =
     Build documentation and API through Sphinx
+changedir = docs
 whitelist_externals =
     make
 commands =
@@ -18,10 +19,11 @@ commands =
 [testenv:linkcheck]
 description =
     Check external links in the documentation (requires internet connection)
+changedir = docs
 whitelist_externals =
     make
 commands =
-    make linkcheck
+    make ignore-warnings=1 linkcheck  # for margin directive
 
 [testenv:sty]
 description =
@@ -41,12 +43,11 @@ commands =
 [flake8]
 application-import-names = pwa_pages
 filename =
-    ./doc/*.py
+    ./src/*.py
 exclude =
     __pycache__
-    doc/conf.py
+    docs/conf.py
 ignore = # more info: https://www.flake8rules.com/
-    B305 # progress.Bar.next()
     E203 # https://github.com/psf/black#slices
     E231 # allowed by black
     E501 # https://github.com/psf/black#line-length
@@ -57,6 +58,7 @@ rst-roles =
     attr,
     class,
     doc,
+    download,
     file,
     func,
     meth,