Initial docs

Author: Martin Schubert

.github/workflows/pages.yml

@@ -0,0 +1,51 @@
+name: Sphinx docs to gh-pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    name: Sphinx docs to gh-pages
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+
+      - name: Setup environment
+        run: |
+            python -m pip install --upgrade pip
+            pip install ".[tests,dev,docs]"
+
+      - name: docs
+        run: jb build docs
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "./docs/_build/html/"
+
+  deploy-docs:
+    needs: build-docs
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -45,9 +45,9 @@ for i in range(steps):
     (value, (response, distance, metrics, aux)), grad = value_and_grad_fn(params)
     state = opt.update(grad=grad, value=value, params=params, state=state)
 ```
-With some plotting (see the [example notebook](notebooks/readme_example.ipynb)), this code will produce the following waveguide bend:
+With some plotting, this code will produce the following waveguide bend:
 
-![Animated evolution of waveguide bend design](docs/img/waveguide_bend.gif)
+![Animated evolution of waveguide bend design](https://github.com/invrs-io/gym/blob/main/docs/img/waveguide_bend.gif?raw=true)
 
 ## Challenges
 The current list of challenges is below. Check out the notebooks for ready-to-go examples of each.

docs/_config.yml

@@ -0,0 +1,49 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: invrs_gym
+author: Martin F. Schubert
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: cache
+  timeout: -1
+  allow_errors: true
+  # execute_notebooks: force
+  # execute_notebooks: "off"
+
+latex:
+  latex_engine: pdflatex # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'
+  use_jupyterbook_latex: true # use sphinx-jupyterbook-latex for pdf builds as default
+
+# Add a bibtex file so that we can create citations
+
+html:
+  home_page_in_navbar: true
+  use_edit_page_button: true
+  use_repository_button: true
+  use_issues_button: true
+  baseurl: https://github.com/invrs-io/gym
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/invrs-io/gym
+  path_to_book: docs # Optional path to your book, relative to the repository root
+  branch: main # Which branch of the repository should be used when creating links (optional)
+
+launch_buttons:
+  notebook_interface: jupyterlab
+  colab_url: "https://colab.research.google.com"
+
+sphinx:
+  extra_extensions:
+    - "sphinx.ext.autodoc"
+    - "sphinx.ext.autodoc.typehints"
+    - "sphinx.ext.autosummary"
+    - "sphinx.ext.napoleon"
+    - "sphinx.ext.viewcode"
+    - "matplotlib.sphinxext.plot_directive"
+  config:
+    autodoc_typehints: description
+    nb_execution_show_tb: True

docs/_toc.yml

@@ -0,0 +1,9 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: readme
+parts:
+  - caption: Challenges
+    chapters:
+    - file: notebooks/ceviche_challenge