docs plumbing

docs/_static/style.css

@@ -0,0 +1,5 @@
+@import url("theme.css");
+
+.wy-side-nav-search {
+  background-color: #fff;
+}

docs/conf.py

@@ -14,39 +14,203 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
 project = 'EMLP'
 copyright = '2021, Marc Finzi'
 author = 'Marc Finzi'
 
+sys.path.append(os.path.abspath('sphinxext'))
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'matplotlib.sphinxext.plot_directive',
+    'sphinx_autodoc_typehints',
+    'myst_nb',
+]
 
-# -- General configuration ---------------------------------------------------
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+}
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
+suppress_warnings = [
+    'ref.citation',  # Many duplicated citations in numpy/scipy docstrings.
+    'ref.footnote',  # Many unreferenced footnotes in numpy/scipy docstrings
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+# The suffix(es) of source filenames.
+# Note: important to list ipynb before md here: we have both md and ipynb
+# copies of each notebook, and myst will choose which to convert based on
+# the order in the source_suffix list. Notebooks which are not executed have
+# outputs stored in ipynb but not in md, so we must convert the ipynb.
+source_suffix = ['.rst', '.ipynb', '.md']
+
+# The master toctree document.
+main_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [
+    # Sometimes sphinx reads its own outputs as inputs!
+    'build/html',
+    'build/jupyter_execute',
+    'notebooks/README.md',
+    'README.md',
+    # Ignore markdown source for notebooks; myst-nb builds from the ipynb
+    # These are kept in sync using the jupytext pre-commit hook.
+    'notebooks/*.md'
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+autosummary_generate = True
+napolean_use_rtype = False
 
+# mathjax_config = {
+#     'TeX': {'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True}},
+# }
+
+# Additional files needed for generating LaTeX/PDF output:
+# latex_additional_files = ['references.bib']
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+# -- Options for myst ----------------------------------------------
+jupyter_execute_notebooks = "force"
+execution_allow_errors = False
+execution_fail_on_error = True  # Requires https://github.com/executablebooks/MyST-NB/pull/296
+
+# Notebook cell execution timeout; defaults to 30.
+execution_timeout = 100
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'EMLPdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# # Grouping the document tree into LaTeX files. List of tuples
+# # (source start file, target name, title,
+# #  author, documentclass [howto, manual, or own class]).
+# latex_documents = [
+#     (main_doc, 'JAX.tex', 'JAX Documentation',
+#      'The JAX authors', 'manual'),
+# ]
+
+
+# # -- Options for manual page output ------------------------------------------
+
+# # One entry per manual page. List of tuples
+# # (source start file, name, description, authors, manual section).
+# man_pages = [
+#     (main_doc, 'jax', 'JAX Documentation',
+#      [author], 1)
+# ]
+
+
+# # -- Options for Texinfo output ----------------------------------------------
+
+# # Grouping the document tree into Texinfo files. List of tuples
+# # (source start file, target name, title, author,
+# #  dir menu entry, description, category)
+# texinfo_documents = [
+#     (main_doc, 'JAX', 'JAX Documentation',
+#      author, 'JAX', 'One line description of project.',
+#      'Miscellaneous'),
+# ]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------
+
+# Tell sphinx-autodoc-typehints to generate stub parameter annotations including
+# types, even if the parameters aren't explicitly documented.
+always_document_param_types = True

docs/index.rst

@@ -14,33 +14,28 @@ A type system for the automated construction of equivariant layers.
    :maxdepth: 1
    :caption: Tutorials
 
-   notebooks/quickstart
-   notebooks/model
-   notebooks/new_groups
+   notebooks/quickstart.md
+   notebooks/model.md
+   notebooks/new_groups.md
 
 .. toctree::
    :maxdepth: 1
    :caption: Advanced Tutorials
-   notebooks/mixed_tensors
-   notebooks/new_representations
+
+   notebooks/mixed_tensors.md
+   notebooks/new_representations.md
 
 .. toctree::
    :maxdepth: 1
    :caption: Notes
 
-   CHANGELOG
+   CHANGELOG.md
 
 .. toctree::
    :maxdepth: 2
    :caption: Developer documentation
 
-   documentation
-
-.. toctree::
-   :maxdepth: 3
-   :caption: API documentation
-
-   api
+   documentation.md
 
 
 Indices and tables

docs/notebooks/mixed_tensors.ipynb

@@ -1,23 +1,10 @@
 {
  "cells": [
   {
-   "cell_type": "code",
-   "execution_count": 1,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "1"
-      ]
-     },
-     "execution_count": 1,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
    "source": [
-    "1"
+    "# mixed_tensors"
    ]
   },
   {
@@ -30,7 +17,7 @@
  ],
  "metadata": {
   "jupytext": {
-   "formats": "ipynb,md"
+   "formats": "ipynb,md:myst"
   },
   "kernelspec": {
    "display_name": "Python 3",

docs/notebooks/mixed_tensors.md

@@ -1,22 +1,19 @@
 ---
-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
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.10.2
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
 ---
 
-```python
-1
-```
+# mixed_tensors
 
-```python
+```{code-cell} ipython3
 
 ```

docs/notebooks/model.ipynb

@@ -1,11 +1,11 @@
 {
  "cells": [
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
-   "source": []
+   "source": [
+    "# Model"
+   ]
   },
   {
    "cell_type": "code",
@@ -37,7 +37,7 @@
  ],
  "metadata": {
   "jupytext": {
-   "formats": "ipynb,md"
+   "formats": "ipynb,md:myst"
   },
   "kernelspec": {
    "display_name": "Python 3",

docs/notebooks/model.md

@@ -1,26 +1,23 @@
 ---
-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
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.10.2
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
 ---
 
-```python
+# Model
 
-```
-
-```python
+```{code-cell} ipython3
 2
 ```
 
-```python
+```{code-cell} ipython3
 
 ```