docs(api): API now available in docs

docs/index.md

@@ -1,5 +1,5 @@
-<p class="maiusc">A <b>fast</b>, fully <b>jittable</b> MiniGrid reimplemented in JAX</p>
-<h1 class="no-bottom-margin">Welcome to <b>NAVIX</b>!</h1>
+<p class="maiusc" style="margin-bottom: 0.5em;">A <b>fast</b>, fully <b>jittable</b> MiniGrid reimplemented in JAX</p>
+<h1>Welcome to <b>NAVIX</b>!</h1>
 
 
 **NAVIX** is a reimplementation of the [MiniGrid](https://minigrid.farama.org/) environment suite in JAX, and leverages JAX’s intermediate language representation to migrate the computation to different accelerators, such as GPUs and TPUs.

docs/requirements.txt

@@ -2,5 +2,8 @@ mkdocs
 mkdocs-material
 mkdocs-jupyter
 mkdocstrings
-mkdocs-mermaid2-plugin
+mkdocstrings-python
+mkdocs-gen-files
+mkdocs-literate-nav
+mkdocs-section-index
 plumkdocs

docs/scripts/gen_doc_stubs.py

@@ -0,0 +1,47 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.nav.Nav()
+
+root = Path(__file__).parent.parent.parent
+src = root / "navix"
+out = "api"
+
+exclude_files = [
+    "_version.py",
+    "config.py"
+]
+
+for path in sorted(src.rglob("*.py")):
+    if path.name in exclude_files:
+        continue
+
+    print("Generating stub for", path)
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path(out, doc_path)
+
+    parts = tuple(module_path.parts)
+    parts = ("navix",) + 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
+
+    if parts:
+        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.relative_to(root))
+
+with mkdocs_gen_files.open(f"{out}/index.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

mkdocs.yml

@@ -21,8 +21,7 @@ nav:
       - "Customizing envs": examples/customisation.ipynb
   - Install: install/index.md
   - Becnhmarks: benchmarks/index.md
-  - API:
-      - api/index.md
+  - API: api/
   - Changelog: https://github.com/epignatelli/navix/releases
 
 # Customization
@@ -50,8 +49,9 @@ theme:
   name: "material"
   logo: assets/images/navix_logo.png
   font:
-    text: Sherpa
+    text: Roboto
     code: Roboto Mono
+
   features:
     - announce.dismiss
     - content.action.edit
@@ -88,18 +88,23 @@ theme:
         icon: material/weather-sunny
         name: Switch to light mode
 
-
 plugins:
   - mkdocs-jupyter
   - mkdocstrings:
       default_handler: python
       handlers:
         python:
+          options:
+            docstring_style: google
           rendering:
             show_source: false
-      # custom_templates: templates
   - search
-  - mermaid2
+  - gen-files:
+      scripts:
+        - docs/scripts/gen_doc_stubs.py # or any other name or path
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
 
 markdown_extensions:
   - toc:
@@ -113,9 +118,4 @@ markdown_extensions:
   - pymdownx.details # For collapsible admonitions
   - pymdownx.superfences
 
-  # - changelog/index.md
-  # - customization.md
-  # - insiders/changelog/*
-  # - setup/extensions/*-
-
 copyright: Copyright © 2023 - 2024 NAVIX Authors