building the docs

docs/_templates/layout.html

@@ -0,0 +1,2 @@
+{% extends "!layout.html" %}
+{% set css_files = css_files + ["_static/style.css"] %}

docs/documentation.md

@@ -0,0 +1,55 @@
+# Update documentation
+
+To rebuild the documentation, install several packages:
+```
+pip install -r docs/requirements.txt
+```
+And then run:
+```
+sphinx-build -b html docs docs/build/html
+```
+This can take a long time because it executes many of the notebooks in the documentation source;
+if you'd prefer to build the docs without exeuting the notebooks, you can run:
+```
+sphinx-build -b html -D jupyter_execute_notebooks=off docs docs/build/html
+```
+You can then see the generated documentation in `docs/build/html/index.html`.
+
+## Update notebooks
+
+We use [jupytext](https://jupytext.readthedocs.io/) to maintain two synced copies of the notebooks
+in `docs/notebooks`: one in `ipynb` format, and one in `md` format. The advantage of the former
+is that it can be opened and executed directly in Colab; the advantage of the latter is that
+it makes it much easier to track diffs within version control.
+
+### Editing ipynb
+
+For making large changes that substantially modify code and outputs, it is easiest to
+edit the notebooks in Jupyter or in Colab. To edit notebooks in the Colab interface,
+open <http://colab.research.google.com> and `Upload` from your local repo.
+Update it as needed, `Run all cells` then `Download ipynb`.
+You may want to test that it executes properly, using `sphinx-build` as explained above.
+
+### Editing md
+
+For making smaller changes to the text content of the notebooks, it is easiest to edit the
+`.md` versions using a text editor.
+
+### Syncing notebooks
+
+After editing either the ipynb or md versions of the notebooks, you can sync the two versions
+using [jupytext](https://jupytext.readthedocs.io/) by running:
+
+```
+$ jupytext --sync docs/notebooks/*
+```
+
+Alternatively, you can run this command via the [pre-commit](https://pre-commit.com/)
+framework by executing the folloing in the main JAX directory:
+
+```
+$ pre-commit run --all
+```
+
+See the pre-commit framework documentation for information on how to set your local git
+environment to execute this automatically.

docs/index.rst

@@ -3,13 +3,44 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to EMLP's documentation!
-================================
+
+EMLP reference documentation
+===========================
+
+A type system for the automated construction of equivariant layers.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials
+
+   notebooks/quickstart
+   notebooks/model
+   notebooks/new_groups
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Advanced Tutorials
+   notebooks/mixed_tensors
+   notebooks/new_representations
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Notes
+
+   CHANGELOG
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Developer documentation
+
+   documentation
+
+.. toctree::
+   :maxdepth: 3
+   :caption: API documentation
 
+   api
 
 
 Indices and tables

docs/make.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+jupytext --sync ./notebooks/*
+sphinx-build -b html . ./build/html

docs/notebooks/mixed_tensors.ipynb

@@ -0,0 +1,55 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "1"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "jupytext": {
+   "formats": "ipynb,md"
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/notebooks/mixed_tensors.md

@@ -0,0 +1,22 @@
+---
+jupyter:
+  jupytext:
+    formats: ipynb,md
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.3'
+      jupytext_version: 1.10.2
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+---
+
+```python
+1
+```
+
+```python
+
+```

docs/notebooks/model.ipynb

@@ -0,0 +1,62 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "2"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "jupytext": {
+   "formats": "ipynb,md"
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/notebooks/model.md

@@ -0,0 +1,26 @@
+---
+jupyter:
+  jupytext:
+    formats: ipynb,md
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.3'
+      jupytext_version: 1.10.2
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+---
+
+```python
+
+```
+
+```python
+2
+```
+
+```python
+
+```

docs/notebooks/new_groups.ipynb

@@ -0,0 +1,55 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "3"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "3"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "jupytext": {
+   "formats": "ipynb,md"
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/notebooks/new_groups.md

@@ -0,0 +1,22 @@
+---
+jupyter:
+  jupytext:
+    formats: ipynb,md
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.3'
+      jupytext_version: 1.10.2
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+---
+
+```python
+3
+```
+
+```python
+
+```