docs: add Jupyter notebook example (#65)

* chore: reorganise example folder
* chore: add .inv files to gitignore
* ci: set requirements to minimal
* ci: execute Jupyter notebook examples
* docs: add jupyter notebooks to documentation pages
* docs: fix contribute link
* docs: fix cleanup notbooks in usage folder
* docs: add pre-commit badge

.travis.yml

@@ -28,11 +28,12 @@ jobs:
     - name: "Build and test documentation"
       python: 3.7
       before_script:
+        - sudo apt-get -y install pandoc
         - pip3 install -r doc/requirements.txt
       script:
         - cd doc
         - make linkcheck
-        - make html
+        - NBSPHINX_EXECUTE='' make html
 
     - name: "Style checks"
       python: 3.6

CONTRIBUTING.md

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

README.md

@@ -4,6 +4,7 @@
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/db8f89e5588041d8a995968262c224ef)](https://www.codacy.com/gh/ComPWA/tensorwaves)
 [![Documentation build status](https://readthedocs.org/projects/tensorwaves/badge/?version=latest)](https://pwa.readthedocs.io/projects/tensorwaves/en/latest/?badge=latest)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
 
 # TensorWaves
 

doc/.gitignore

@@ -1,3 +1,9 @@
+# Build files
 *.doctree
+*.inv
 *build/
 api/
+
+# Copied files
+*.yml
+*.yaml

doc/conf.py

@@ -6,10 +6,44 @@
 https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 
+import os
 import shutil
 import subprocess
 
 
+# -- Copy example notebooks ---------------------------------------------------
+print("Copy example notebook files")
+# Remove old notebooks
+PATH_TARGET = "usage"
+for root, _, files in os.walk(PATH_TARGET):
+    for notebook in files:
+        if notebook.endswith(".ipynb"):
+            full_path = os.path.join(root, notebook)
+            print("  removing notebook", full_path)
+            os.remove(full_path)
+# Copy notebooks from example directory
+PATH_SOURCE = "../examples"
+for root, _, files in os.walk(PATH_SOURCE):
+    for notebook in files:
+        if ".ipynb_checkpoints" in root:
+            continue
+        if not notebook.endswith(".ipynb"):
+            continue
+        path_from = os.path.join(root, notebook)
+        path_to = os.path.join(PATH_TARGET, notebook)
+        print("  copy", path_from, "to", path_to)
+        shutil.copyfile(path_from, path_to, follow_symlinks=True)
+
+DATA_FILES = [
+    "intensity-recipe.yaml",
+]
+for data_file in DATA_FILES:
+    path_from = os.path.join(PATH_SOURCE, data_file)
+    path_to = data_file
+    print("  copy", path_from, "to", path_to)
+    shutil.copyfile(path_from, path_to, follow_symlinks=True)
+
+
 # -- Generate API skeleton ----------------------------------------------------
 shutil.rmtree("api", ignore_errors=True)
 subprocess.call(
@@ -35,12 +69,16 @@
 
 
 # -- General configuration ---------------------------------------------------
-source_suffix = ".rst"
+source_suffix = [
+    ".rst",
+    ".ipynb",
+]
 
 # The master toctree document.
 master_doc = "index"
 
 extensions = [
+    "nbsphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.autosummary",
@@ -54,6 +92,7 @@
     "sphinx_autodoc_typehints",
 ]
 exclude_patterns = [
+    "**.ipynb_checkpoints",
     "*build",
     "test",
     "tests",
@@ -113,3 +152,14 @@
 linkcheck_ignore = [
     "https://pypi.org/project/tensorwaves",
 ]
+
+# Settings for nbsphinx
+if "NBSPHINX_EXECUTE" in os.environ:
+    nbsphinx_execute = "always"
+else:
+    nbsphinx_execute = "never"
+nbsphinx_timeout = -1
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'svg', 'pdf'}",
+    "--InlineBackend.rc={'figure.dpi': 96}",
+]

doc/contribute.rst

@@ -4,8 +4,8 @@ How to contribute?
 Some recommended packages for Python development
 ------------------------------------------------
 
-* `pytest <https://docs.pytest.org/en/latest/>`_: Run :code:`pytest` in the main
-  folder of the repository to run all :file:`test_*.py` files
+* `pytest <https://docs.pytest.org/en/latest/>`_: Run :code:`pytest` in the
+  main folder of the repository to run all :file:`test_*.py` files
 
 * `pylint <https://www.pylint.org/>`_: Scan your code for naming conventions
   and proper use of Python
@@ -48,9 +48,8 @@ Git
 ---
 
 * Please use
-  `conventional commit messages
-  <https://www.conventionalcommits.org/>`_: start the commit with a semantic
-  keyword (see e.g. `Angular
+  `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>`_,
@@ -69,7 +68,8 @@ Python
 
 * Any Python file that's part of a module should contain (in this order):
 
-  1. A docstring describing what the file contains and does, followed by two empty lines.
+  1. A docstring describing what the file contains and does, followed by two
+  empty lines.
 
   2. A definition of `__all__
      <https://docs.python.org/3/tutorial/modules.html#importing-from-a-package>`_,
@@ -79,9 +79,11 @@ Python
   3. Only after these come the :code:`import` statements, following the
      :pep:`8` conventions for imports.
 
-* When calling or defining multiple arguments of a function and multiple entries in a data container, split the entries over multiple lines and end the last entry with a comma, like so:
+* When calling or defining multiple arguments of a function and multiple
+  entries in a data container, split the entries over multiple lines and end the
+  last entry with a comma, like so:
 
-  .. code-block: python
+  .. code-block:: python
 
     __all__ = [
         'core',

doc/index.rst

@@ -22,6 +22,10 @@
    :alt: Code style: black
    :target: https://github.com/psf/black
 
+.. 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
+
 |
 
 Welcome to TensorWaves!
@@ -67,6 +71,7 @@ it easy to contribute. Physics research is our end goal after all.
    :hidden:
 
    installation
+   usage
    contribute
 
 

doc/requirements.txt

@@ -1,4 +1,9 @@
-sphinx==2.4.4
-sphinx-autodoc-typehints==1.10.3
+doc8>=0.8.0
+jupyter
+matplotlib>=3
+nbsphinx==0.5.1
+pandas>=1
+sphinx-autodoc-typehints>=1.10.3
+sphinx>=2.4.4
 sphinx_rtd_theme
-sphobjinv==2.0.1
+sphobjinv>=2.0.1

doc/usage.rst

@@ -0,0 +1,13 @@
+Usage
+=====
+
+The examples in the following pages illustrate how to use the tools that
+`tensorwaves` offers. The examples were written as Jupyter notebooks and can be
+downloaded `here
+<https://github.com/ComPWA/tensorwaves/tree/master/examples>`_.
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   usage/*

doc/usage/.gitignore

@@ -0,0 +1,14 @@
+# Copied notebooks
+*.ipynb
+
+# nbconvert output
+*.html
+
+# Output files
+*.dat
+*.pkl
+*.png
+*.root
+*.xml
+*.yaml
+*.yml