Generate API docs with Sphinx (#235)

Author: cswinter

.gitignore

@@ -11,3 +11,8 @@ __pycache__
 
 # Meld
 *.orig
+
+# Docs
+entity_gym/docs/build
+entity_gym/docs/source/generated
+entity_gym/docs/source/entity_gym

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+    # You can also specify other tool versions:
+    # nodejs: "16"
+    # rust: "1.55"
+    # golang: "1.17"
+  apt_packages:
+    - graphviz
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: entity_gym/docs/source/conf.py
+
+python:
+  # Install our python package before building the docs
+  install:
+    - requirements: entity_gym/docs/requirements.txt
+    - method: pip
+      path: entity_gym

CONTRIBUTING.md

@@ -74,3 +74,25 @@ poetry run pre-commit run --all-files
 ```bash
 poetry run pytest .
 ```
+
+## Building docs
+
+To build the documentation for entity-gym, go to the entity_gym/docs folder and run the following command:
+
+```bash
+poetry run make html
+```
+
+You can use [watchexec](https://github.com/watchexec/watchexec) to automatically rebuild the documentation on changes:
+
+```
+watchexec -w ../entity_gym -w source -i source/generated -i source/entity_gym -- poetry run make html
+```
+
+You can view the generated docs by openaing `entity_gym/docs/build/html` in a browser.
+
+Some files won't be automatically cleaned up after the build, so you can manually clean up the build directory by running:
+
+```
+poetry run make clean && rm -rf source/generated source/entity_gym
+```

enn_ppo/enn_ppo/agent.py

@@ -5,11 +5,11 @@
 import torch
 from ragged_buffer import RaggedBufferBool, RaggedBufferF32, RaggedBufferI64
 
-import entity_gym.agent
-from entity_gym.environment import Action, Observation, VecActionMask
-from entity_gym.environment.env_list import action_index_to_actions
-from entity_gym.environment.environment import ActionName
-from entity_gym.environment.vec_env import batch_obs
+import entity_gym.runner
+from entity_gym.env import Action, Observation, VecActionMask
+from entity_gym.env.env_list import action_index_to_actions
+from entity_gym.env.environment import ActionName
+from entity_gym.env.vec_env import batch_obs
 from entity_gym.simple_trace import Tracer
 from rogue_net.rogue_net import RogueNet
 
@@ -48,7 +48,7 @@ def get_auxiliary_head(
         ...
 
 
-class RogueNetAgent(entity_gym.agent.Agent):
+class RogueNetAgent(entity_gym.runner.Agent):
     def __init__(self, agent: RogueNet):
         self.agent = agent
 

enn_ppo/enn_ppo/eval.py

@@ -9,8 +9,8 @@
 from enn_ppo.agent import PPOAgent
 from enn_ppo.config import EnvConfig, EvalConfig, RolloutConfig
 from enn_ppo.rollout import Rollout
-from entity_gym.environment import *
-from entity_gym.environment.add_metrics_wrapper import AddMetricsWrapper
+from entity_gym.env import *
+from entity_gym.env.add_metrics_wrapper import AddMetricsWrapper
 from entity_gym.serialization import SampleRecordingVecEnv
 from entity_gym.simple_trace import Tracer
 

enn_ppo/enn_ppo/gae.py

@@ -4,7 +4,7 @@
 import torch
 
 from enn_ppo.agent import PPOAgent
-from entity_gym.environment import *
+from entity_gym.env import *
 from entity_gym.simple_trace import Tracer
 
 from .config import *

enn_ppo/enn_ppo/ppo.py

@@ -4,7 +4,7 @@
 from ragged_buffer import RaggedBufferF32
 
 from enn_ppo.config import PPOConfig
-from entity_gym.environment.environment import ActionName
+from entity_gym.env.environment import ActionName
 from entity_gym.simple_trace import Tracer
 
 

enn_ppo/enn_ppo/rollout.py

@@ -7,8 +7,8 @@
 from ragged_buffer import RaggedBufferBool, RaggedBufferF32, RaggedBufferI64
 
 from enn_ppo.agent import PPOAgent
-from entity_gym.environment import *
-from entity_gym.environment.vec_env import Metric
+from entity_gym.env import *
+from entity_gym.env.vec_env import Metric
 from entity_gym.ragged_dict import RaggedActionDict, RaggedBatchDict
 from entity_gym.serialization.sample_recorder import SampleRecordingVecEnv
 from entity_gym.simple_trace import Tracer

enn_ppo/enn_ppo/supervised.py

@@ -13,7 +13,7 @@
 from ragged_buffer import RaggedBufferBool, RaggedBufferF32, RaggedBufferI64
 from torch.optim import AdamW
 
-from entity_gym.environment.vec_env import VecActionMask
+from entity_gym.env.vec_env import VecActionMask
 from entity_gym.ragged_dict import RaggedActionDict, RaggedBatchDict
 from entity_gym.serialization import Trace
 from entity_gym.serialization.sample_loader import Episode, MergedSamples

enn_ppo/enn_ppo/train.py

@@ -24,9 +24,9 @@
 from enn_ppo.gae import returns_and_advantages
 from enn_ppo.ppo import ppo_loss, value_loss
 from enn_ppo.rollout import Rollout
-from entity_gym.environment import *
-from entity_gym.environment.add_metrics_wrapper import AddMetricsWrapper
-from entity_gym.environment.validator import ValidatingEnv
+from entity_gym.env import *
+from entity_gym.env.add_metrics_wrapper import AddMetricsWrapper
+from entity_gym.env.validator import ValidatingEnv
 from entity_gym.examples import ENV_REGISTRY
 from entity_gym.serialization import SampleRecordingVecEnv
 from entity_gym.simple_trace import Tracer