Use doc setup from pyDVL.

.gitignore

@@ -134,3 +134,6 @@ dmypy.json
 
 # Temporary
 runs/
+
+# Docs
+docs_build

build_scripts/copy_changelog.py

@@ -0,0 +1,38 @@
+import logging
+import os
+from pathlib import Path
+
+import mkdocs.plugins
+
+logger = logging.getLogger(__name__)
+
+root_dir = Path(__file__).parent.parent
+docs_dir = root_dir / "docs"
+changelog_file = root_dir / "CHANGELOG.md"
+target_filepath = docs_dir / changelog_file.name
+
+
+@mkdocs.plugins.event_priority(100)
+def on_pre_build(config):
+    logger.info("Temporarily copying changelog to docs directory")
+    try:
+        if os.path.getmtime(changelog_file) <= os.path.getmtime(target_filepath):
+            logger.info(
+                f"Changelog '{os.fspath(changelog_file)}' hasn't been updated, skipping."
+            )
+            return
+    except FileNotFoundError:
+        pass
+    logger.info(
+        f"Creating symbolic link for '{os.fspath(changelog_file)}' "
+        f"at '{os.fspath(target_filepath)}'"
+    )
+    target_filepath.symlink_to(changelog_file)
+
+    logger.info("Finished copying changelog to docs directory")
+
+
+@mkdocs.plugins.event_priority(-100)
+def on_shutdown():
+    logger.info("Removing temporary changelog in docs directory")
+    target_filepath.unlink()

build_scripts/copy_notebooks.py

@@ -0,0 +1,44 @@
+import logging
+import os
+from pathlib import Path
+
+import mkdocs.plugins
+
+logger = logging.getLogger(__name__)
+
+root_dir = Path(__file__).parent.parent
+docs_examples_dir = root_dir / "docs" / "examples"
+notebooks_dir = root_dir / "notebooks"
+
+
+@mkdocs.plugins.event_priority(100)
+def on_pre_build(config):
+    logger.info("Temporarily copying notebooks to examples directory")
+    docs_examples_dir.mkdir(parents=True, exist_ok=True)
+    notebook_filepaths = list(notebooks_dir.glob("*.ipynb"))
+
+    for notebook in notebook_filepaths:
+        target_filepath = docs_examples_dir / notebook.name
+
+        try:
+            if os.path.getmtime(notebook) <= os.path.getmtime(target_filepath):
+                logger.info(
+                    f"Notebook '{os.fspath(notebook)}' hasn't been updated, skipping."
+                )
+                continue
+        except FileNotFoundError:
+            pass
+        logger.info(
+            f"Creating symbolic link for '{os.fspath(notebook)}' "
+            f"at '{os.fspath(target_filepath)}'"
+        )
+        target_filepath.symlink_to(notebook)
+
+    logger.info("Finished copying notebooks to examples directory")
+
+
+@mkdocs.plugins.event_priority(-100)
+def on_shutdown():
+    logger.info("Removing temporary examples directory")
+    for notebook_file in docs_examples_dir.glob("*.ipynb"):
+        notebook_file.unlink()

scripts/gen_ref_pages.py → build_scripts/generate_api_docs.py

@@ -1,18 +1,14 @@
-"""Generate the code reference pages and navigation."""
-
+"""Generate the code reference pages."""
 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)
-
+root = Path("src")
+for path in sorted(root.rglob("*.py")):
+    module_path = path.relative_to(root).with_suffix("")
+    doc_path = path.relative_to(root).with_suffix(".md")
+    full_doc_path = Path("api") / doc_path
     parts = tuple(module_path.parts)
 
     if parts[-1] == "__init__":
@@ -25,10 +21,7 @@
     nav[parts] = doc_path.as_posix()
 
     with mkdocs_gen_files.open(full_doc_path, "w") as fd:
-        ident = ".".join(parts)
-        fd.write(f"::: {ident}")
+        identifier = ".".join(parts)
+        fd.write(f"::: {identifier}")
 
     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())

docs/css/extra.css

@@ -0,0 +1,100 @@
+
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="rgb(0, 0, 0)" d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  position: relative;
+  top: 0.1em;
+  margin-left: 0.2em;
+  margin-right: 0.1em;
+
+  height: 1em;
+  width: 1em;
+  border-radius: 100%;
+  background-color: var(--md-typeset-a-color);
+}
+
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}
+
+/* Headers */
+.md-typeset h1 {
+  font-size: 2.5em;
+  font-weight: 500;
+}
+
+.md-typeset h2 {
+  font-size: 1.3em;
+  font-weight: 300;
+}
+
+.md-typeset h3 {
+  font-size: 1.1em;
+  font-weight: 300;
+}
+
+/* Highlight function names in red */
+.highlight > :first-child  {
+    color: #b30000;
+}
+
+/* Prevent selection of >>>, ... and output in Python code blocks */
+.highlight .gp, .highlight .go { /* Generic.Prompt, Generic.Output */
+    user-select: none;
+}
+
+/* Remove cell input and output prompt */
+.jp-InputArea-prompt, .jp-OutputArea-prompt {
+    display: none !important;
+}
+
+/* Alert boxes */
+.alert {
+  border-radius: 0.375rem;
+  padding: 1rem;
+  position: relative;
+  margin: auto;
+  text-align: center;
+}
+
+.alert-info {
+  background: var(--md-typeset-ins-color);
+  border: 0.1rem solid var(--md-primary-fg-color);
+}
+
+.alert-warning {
+  background: var(--md-warning-bg-color);
+  border: 0.1rem solid var(--md-primary-fg-color);
+  color: black;
+}
+
+body[data-md-color-scheme="default"] .invertible img {
+}
+
+body[data-md-color-scheme="slate"] .invertible img {
+    filter: invert(100%) hue-rotate(180deg);
+}
+
+body[data-md-color-scheme="slate"] .celltag_invertible-output img {
+    filter: invert(100%) hue-rotate(180deg);
+}
+
+/* Rendered dataframe from jupyter */
+table.dataframe {
+    display: block;
+    max-width: -moz-fit-content;
+    max-width: fit-content;
+    margin: 0 auto;
+    overflow-x: auto;
+    white-space: nowrap;
+}

docs/getting-started/installation.md

@@ -0,0 +1,15 @@
+---
+title: Installing Continuity
+alias:
+    name: installation
+    text: Installing Continuity
+---
+
+# Installing Continuity
+
+Clone the repository and install the package using pip.
+```
+git clone https://github.com/aai-institute/Continuity.git
+cd Continuity
+pip install -e .
+```

docs/index.md

@@ -1,5 +1,8 @@
-Continuity
-==========
+---
+title: Home
+---
+
+# Continuity
 
 **Continuity** is a Python package for *learning function operators with neural
 networks*.
@@ -9,8 +12,20 @@ learning on functions operators. 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/index.md).
+::cards:: cols=2
+
+- title: Installation
+  content: Steps to install and requirements
+  url: getting-started/installation.md
+
+- title: Learning Operators
+  content: >
+    Basics of learning function operators with neural networks
+  url: operators/index.md
+
+- title: Browse the API
+  content: Full documentation of the API
+  url: api/continuity/index.md
+
+::/cards::

docs/javascript/mathjax.js

@@ -0,0 +1,16 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise()
+})

docs/operators/index.md

@@ -0,0 +1,8 @@
+---
+title: Learning Operators
+alias:
+  name: operators
+  text: Learning Operators
+---
+
+Mathematical operators map functions to functions.

docs/overrides/partials/copyright.html

@@ -0,0 +1,19 @@
+<div class="md-copyright">
+  {% if config.copyright %}
+    <div class="md-copyright__highlight">
+        {% if config.extra.copyright_link %}
+        <a href="{{ config.extra.copyright_link }}">
+            {{ config.copyright }}
+        </a>
+        {% else %}
+        {{ config.copyright }}
+        {% endif %}
+    </div>
+  {% endif %}
+  {% if not config.extra.generator == false %}
+    Made with
+    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
+      Material for MkDocs
+    </a>
+  {% endif %}
+</div>

docs/requirements.txt

@@ -1,5 +1,16 @@
-mkdocs
+markdown-captions
+mike
+mkdocs==1.5.2
+mkdocs-alias-plugin>=0.6.0
+mkdocs-autorefs
 mkdocs-gen-files
+mkdocs-git-revision-date-localized-plugin
+mkdocs-glightbox
 mkdocs-literate-nav
+mkdocs-macros-plugin
 mkdocs-material
-mkdocstrings-python
+mkdocs-section-index
+mkdocstrings[python]>=0.18
+mknotebooks>=0.8.0
+neoteroi-mkdocs
+pygments