Add mkdocstrings_handlers.

.github/workflows/docs.yml

@@ -1,10 +1,14 @@
-name: docs
+name: Documentation
+
 on:
   push:
-    branches:
-      - main
+    branches: [main]
+  pull_request:
+    branches: [main]
+
 permissions:
   contents: write
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -16,13 +20,14 @@ jobs:
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
       - uses: actions/setup-python@v4
         with:
-          python-version: 3.x
+          python-version: 3.11
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v3
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: pip install mkdocs-material mkdocstrings
+      - run: pip install -r docs/requirements.txt
+      - run: pip install -e .
       - run: mkdocs gh-deploy --force

docs/about.md

@@ -1,2 +1,7 @@
 About
 ==========
+
+**Authors**:
+Samuel Burbulla (2023)
+
+AppliedAI Institute for Europe gGmbH

docs/index.md

@@ -1,4 +1,16 @@
 Continuity
 ==========
 
-Mapping continuous functions with neural networks.
+**Continuity** is a Python package for *mapping continuous functions with neural
+networks*.
+
+This package is based on PyTorch and provides a general interface for machine
+learning on continuous functions. It implements various neural network
+architectures, including DeepONets or neural operators, physics-informed loss
+functions to train the networks based on PDEs, and a variety of benchmarks.
+
+### Installation
+See [Installation](installation.md) for details on how to install **Continuity**.
+
+### Reference
+The module documentation can be found in [Reference](/reference/continuity).

docs/installation.md

@@ -1,6 +1,14 @@
 Installation
 ============
 
+It is recommended to install **Continuity** in a virtual environment.
+```
+python3 -m venv venv
+source venv/bin/activate
+```
+
+For a editable installation, clone the repository and install the
+package using pip.
 ```
 git clone https://github.com/aai-institute/Continuity.git
 cd Continuity

docs/requirements.txt

@@ -1,2 +1,5 @@
 mkdocs
-mkdocstrings
+mkdocs-gen-files
+mkdocs-literate-nav
+mkdocs-material
+mkdocstrings-python

mkdocs.yml

@@ -2,13 +2,30 @@ site_name: Continuity
 nav:
   - Home: index.md
   - Installation: installation.md
-  - Documentation: documentation.md
   - About: about.md
+  - Reference: reference/
+
 theme:
   name: readthedocs
   locale: "en"
   logo: img/logo.png
+  repo: fontawesome/brands/github
+
+repo_url: https://github.com/aai-institute/Continuity
+edit_uri: edit/main/docs/
 
 plugins:
   - search
-  - mkdocstrings
+  - autorefs
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            show_root_heading: true
+            show_source: false
+  - gen-files:
+      scripts:
+        - scripts/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md

scripts/gen_ref_pages.py

@@ -0,0 +1,34 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+src = Path(__file__).parent.parent / "src"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

src/continuity/__init__.py

@@ -0,0 +1 @@
+"""The Continuity package."""

src/continuity/data/dataset.py

@@ -1,3 +1,5 @@
+"""Provide base classes for data sets."""
+
 import math
 from numpy import ndarray
 from typing import List, Optional
@@ -46,8 +48,13 @@ def __str__(self):
         s += ")"
         return s
 
-    def to_tensor(self):
-        """Convert observation to tensor"""
+    def to_tensor(self) -> torch.Tensor:
+        """Convert observation to tensor.
+
+        Returns:
+            Tensor of shape (num_sensors, coordinate_dim + num_channels)
+
+        """
         u = torch.zeros((self.num_sensors, self.coordinate_dim + self.num_channels))
         for i, sensor in enumerate(self.sensors):
             u[i] = torch.concat([tensor(sensor.x), tensor(sensor.u)])

src/continuity/model/neuraloperator.py

@@ -81,8 +81,8 @@ def __init__(
             coordinate_dim: Dimension of coordinate space
             num_channels: Number of channels
             depth: Number of hidden layers
-            width: Width of kernel network
-            depth: Depth of kernel network
+            kernel_width: Width of kernel network
+            kernel_depth: Depth of kernel network
         """
         super().__init__()