Merge pull request #74 from epignatelli/docs

Add API docs

.github/workflows/CD.yml

@@ -28,12 +28,7 @@ jobs:
         uses: TriPSs/conventional-changelog-action@v3
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
-          input-file: CHANGELOG.md
-          output-file: CHANGELOG.md
           fallback-version: ${{ env.NAVIX_VERSION }}
-          skip-commit: false
-          skip-tag: true
-
 
       - name: Create Release
         uses: ncipollo/release-action@v1
@@ -70,6 +65,7 @@ jobs:
       - name: Setup navix
         run: |
           pip install . -v
+          pip install -r docs/requirements.txt
       - name: Build docs
         run: |
           mkdocs build

CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased

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,9 +21,8 @@ nav:
       - "Customizing envs": examples/customisation.ipynb
   - Install: install/index.md
   - Becnhmarks: benchmarks/index.md
-  - API:
-      - api/index.md
-  - Changelog: changelog.md
+  - API: api/
+  - Changelog: https://github.com/epignatelli/navix/releases
 
 # Customization
 extra:
@@ -49,7 +48,9 @@ extra_javascript:
 theme:
   name: "material"
   logo: assets/images/navix_logo.png
-  font: "Sherpa"
+  font:
+    text: Roboto
+    code: Roboto Mono
 
   features:
     - announce.dismiss
@@ -74,34 +75,43 @@ theme:
 
   palette:
     - scheme: default
-      primary: yellow
+      primary: pink
       accent: red
       toggle:
         icon: material/weather-night
         name: Switch to dark mode
 
     - scheme: slate
-      primary: yellow
+      primary: light green
       accent: red
       toggle:
         icon: material/weather-sunny
         name: Switch to light mode
 
-  font:
-    text: Roboto
-    code: Roboto Mono
-
 plugins:
   - mkdocs-jupyter
   - mkdocstrings:
       default_handler: python
       handlers:
         python:
-          rendering:
+          options:
+            docstring_style: google
+            show_bases: true
             show_source: false
-      # custom_templates: templates
+            heading_level: 3
+            show_root_full_path: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            show_signature: true
+            show_signature_annotations: false
+            signature_crossrefs: false
   - 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:
@@ -115,9 +125,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

navix/_version.py

@@ -18,5 +18,5 @@
 # under the License.
 
 
-__version__ = "0.6.9"
+__version__ = "0.6.10"
 __version_info__ = tuple(int(i) for i in __version__.split(".") if i.isdigit())

navix/actions.py

@@ -16,6 +16,10 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
+"""The *action* system determines the next state of the environment \
+given the current state and an action."""
+
+
 from __future__ import annotations
 from typing import Tuple
 
@@ -85,38 +89,92 @@ def _move(state: State, direction: Array) -> State:
 
 
 def noop(state: State) -> State:
+    """No operation. Does nothing.
+
+    Args:
+        state (State): The current state.
+    
+    Returns:
+        State: The same state."""
     return state
 
 
 def rotate_cw(state: State) -> State:
+    """Rotates the player clockwise.
+    
+    Args:
+        state (State): The current state.
+    
+    Returns:
+        State: The new state with the player rotated clockwise."""
     return _rotate(state, 1)
 
 
 def rotate_ccw(state: State) -> State:
+    """Rotates the player counter-clockwise.
+    
+    Args:
+        state (State): The current state.
+
+    Returns:
+        State: The new state with the player rotated counter-clockwise."""
     return _rotate(state, -1)
 
 
 def forward(state: State) -> State:
+    """Moves the player forward.
+    
+    Args:
+        state: The current state.
+
+    Returns:
+        State: The new state with the player moved forward."""
     player = state.get_player(idx=0)
     return _move(state, player.direction)
 
 
 def right(state: State) -> State:
+    """Steps the player to the right without changing the direction.
+
+    Args:
+        state (State): The current state.
+
+    Returns:
+        State: The new state with the player moved to the right."""
     player = state.get_player(idx=0)
     return _move(state, player.direction + 1)
 
 
 def backward(state: State) -> State:
+    """Steps the player backward without changing the direction.
+        
+        Args:
+            state (State): The current state.
+
+        Returns:
+            State: The new state with the player moved backward."""
     player = state.get_player(idx=0)
     return _move(state, player.direction + 2)
 
 
 def left(state: State) -> State:
+    """Steps the player to the left without changing the direction.
+
+    Args:
+        state (State): The current state.
+    
+    Returns:
+        State: The new state with the player moved to the left."""
     player = state.get_player(idx=0)
     return _move(state, player.direction + 3)
 
 
 def pickup(state: State) -> State:
+    """Picks up an item in front of the player and puts it in the pocket.
+    Args:
+        state (State): The current state.
+    Returns:
+        State: The new state with the player entity having the item in the pocket."""
     if Entities.KEY not in state.entities:
         return state
 
@@ -151,7 +209,13 @@ def pickup(state: State) -> State:
 
 
 def drop(state: State) -> State:
-    """Replaces the position in front of the player with the item in the pocket."""
+    """Replaces the position in front of the player with the item in the pocket.
+
+    Args:
+        state (State): The current state.
+    
+    Returns:
+        State: The new state with the item in the pocket dropped in front of the player."""
     player = state.get_player(idx=0)
 
     position_in_front = translate(player.position, player.direction)
@@ -171,12 +235,24 @@ def drop(state: State) -> State:
 
 
 def toggle(state: State) -> State:
+    """Toggles an openable object (like a door) if possible.
+
+    Args:
+        state (State): The current state.
+    
+    Returns:
+        State: The new state with the openable object toggled."""
     return open(state)
 
 
 def open(state: State) -> State:
-    """Unlocks and opens an openable object (like a door) if possible"""
-
+    """Unlocks and opens an openable object (like a door) if possible.
+    
+    Args:
+        state (State): The current state.
+    
+    Returns:
+        State: The new state with the openable object opened."""
     if Entities.DOOR not in state.entities:
         return state
 
@@ -221,6 +297,14 @@ def open(state: State) -> State:
 
 
 def done(state: State) -> State:
+    """A placeholder action that does nothing, but is a signal to the environment that the episode is over.
+    This action does not terminate the episode, unless the termination function explicitly checks for it (not default).
+    
+    Args:
+        state (State): The current state.
+    
+    Returns:
+        State: The same state."""
     return state
 
 
@@ -249,6 +333,8 @@ def done(state: State) -> State:
     open,
     done,
 )
+"""Complete action set for the environment.
+This set includes all the actions that can be taken by the agent, and does not mirror the Minigrid action set."""
 
 MINIGRID_ACTION_SET = (
     rotate_ccw,
@@ -259,5 +345,7 @@ def done(state: State) -> State:
     toggle,
     done,
 )
+"""Default action set from Minigrid. See
+https://github.com/Farama-Foundation/Minigrid/blob/master/minigrid/core/actions.py"""
 
 DEFAULT_ACTION_SET = MINIGRID_ACTION_SET