Issue #140: Renaming, documentation, and data refactor

.github/pull_request_template.md

@@ -17,9 +17,9 @@ Please include a summary, motivation, and context of the changes and the related
 Please describe the tests that you ran to verify your changes.
 
 ### Passes Tests
-- [ ] __Unit tests__ (General Environment only) `pytest --cov bsk_rl/env --cov-report term-missing tests/unittest`
-- [ ] __Integrated tests__ (General Environment only) `pytest --cov bsk_rl/env --cov-report term-missing tests/integration`
-- [ ] __Examples__ (General Environment only) `pytest tests/examples`
+- [ ] __Unit tests__ `pytest --cov bsk_rl --cov-report term-missing tests/unittest`
+- [ ] __Integrated tests__ `pytest --cov bsk_rl --cov-report term-missing tests/integration`
+- [ ] __Documentation builds__ `cd docs; make html`
 
 ### Test Configuration
 - Python:
@@ -30,8 +30,9 @@ Please describe the tests that you ran to verify your changes.
 
 - [ ] My code follows the style guidelines of this project (passes Black, ruff, and isort)
 - [ ] I have performed a self-review of my code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
+- [ ] I have commented my code in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation and release notes
 - [ ] Commit messages are atomic, are in the form `Issue #XXX: Message` and have a useful message
 - [ ] My changes generate no new warnings
 - [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] If I changed an example ipynb, I have locally rebuilt the documentation

.github/workflows/documentation.yml

@@ -25,7 +25,7 @@ jobs:
           cp docs/sitecustomize.py $(python -c 'import site; print(site.getsitepackages()[0])')/sitecustomize.py
       - name: Install dependencies
         run: |
-          pip install -e .
+          pip install -e '.[docs]'
         # skip finish install steps
       - name: Sphinx build
         run: |

.github/workflows/documentation_refactor.yml

@@ -0,0 +1,44 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - refactor/v1_0_0
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+    contents: write
+    pages: write
+    id-token: write
+
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: pandoc/actions/setup@main
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+        with:
+            python-version: '3.10'     
+      - name: Mock Basilisk
+        run: |
+          cp docs/sitecustomize.py $(python -c 'import site; print(site.getsitepackages()[0])')/sitecustomize.py
+      - name: Install dependencies
+        run: |
+          pip install -e '.[docs,rllib]'
+        # skip finish install steps
+      - name: Sphinx build
+        run: |
+          cd docs
+          make html
+          cd ..
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build/html
+          force_orphan: true
+          publish_branch: gh-pages-refactor
+
+

.gitignore

@@ -13,7 +13,6 @@ __pycache__/
 # Distribution / packaging
 .Python
 bin/
-build/
 develop-eggs/
 dist/
 downloads/
@@ -66,11 +65,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
-docs/source/API Reference
-docs/source/Examples
-
 # Pickles
 *.pkl
 
@@ -125,4 +119,15 @@ bsk_rl/results/
 .DS_Store
 
 # data files
-src/bsk_rl/data/simplemaps_worldcities/
+src/bsk_rl/_dat/simplemaps_worldcities/
+
+# Sphinx documentation
+/docs/build/*
+/docs/source/api_reference/*
+/docs/source/examples/*
+
+# executed ipynb cache
+!/docs/build/doctrees
+docs/build/doctrees/*
+!/docs/build/doctrees/nbsphinx
+!/docs/build/doctrees/nbsphinx/*

.isort.cfg

@@ -1,2 +1,2 @@
 [settings]
-profile=black
+profile=black

.ruff.toml

@@ -1 +1 @@
-ignore-init-module-imports = true
+extend-include = ["*.ipynb"]

README.md

@@ -1,7 +1,14 @@
-# BSK-RL: Environments and Algorithms for Spacecraft Planning and Scheduling
-[BSK-RL](https://avslab.github.io/bsk_rl/) ([Basilisk](https://hanspeterschaub.info/basilisk) + [Reinforcement Learning](https://en.wikipedia.org/wiki/Reinforcement_learning)) is a Python package for constructing [Gymnasium](https://gymnasium.farama.org/index.html) environments for spacecraft tasking problems. It is built on top of [Basilisk](https://hanspeterschaub.info/basilisk), a modular and fast spacecraft simulation framework, making the simulation environments high-fidelity and computationally efficient. BSK-RL also includes a collection of agents, training scripts, and examples for working with these environments.
+# BSK-RL: Environments for Spacecraft Planning and Scheduling
+
+<img align="right" src="./docs/source/_images/static/bsk_rl-logo.png" width=180px>
+
+
+[BSK-RL](https://avslab.github.io/bsk_rl/) ([Basilisk](https://hanspeterschaub.info/basilisk) + [Reinforcement Learning](https://en.wikipedia.org/wiki/Reinforcement_learning)) is a Python package for constructing [Gymnasium](https://gymnasium.farama.org/index.html) environments for spacecraft tasking problems. It is built on top of [Basilisk](https://hanspeterschaub.info/basilisk), a modular and fast spacecraft simulation framework, making the simulation environments high-fidelity and computationally efficient. 
+
+### Usage
+Installation instructions, examples, and documentation can be found on the [BSK-RL website](https://avslab.github.io/bsk_rl/).
+
+### Acknowledgment
 
 BSK-RL is developed by the [Autonomous Vehicle Systems (AVS) Lab](https://hanspeterschaub.info/AVSlab.html) at the University of Colorado Boulder.
 
-## Usage
-Installation instructions, examples, and documentation can be found on the [BSK-RL website](https://avslab.github.io/bsk_rl/) (under construction).

deprecated/environments/agile_eos/gym_env.py

@@ -3,7 +3,7 @@
 from Basilisk.utilities import macros as mc
 from gymnasium import spaces
 
-from bsk_rl.env.agile_eos.bsk_sim import AgileEOSSimulator
+from bsk_rl.scene.agile_eos.bsk_sim import AgileEOSSimulator
 
 
 class AgileEOS(gym.Env):

deprecated/environments/multisat_agile_eos/bsk_sim.py

@@ -7,9 +7,9 @@
 from Basilisk.utilities import orbitalMotion, vizSupport
 from scipy.sparse.csgraph import connected_components
 
-from bsk_rl.env.multisat_agile_eos.bsk_models import dynamics, environment
-from bsk_rl.env.multisat_agile_eos.bsk_models import fsw as fsw_feedback
-from bsk_rl.env.multisat_agile_eos.bsk_models import fsw_steering
+from bsk_rl.scene.multisat_agile_eos.bsk_models import dynamics, environment
+from bsk_rl.scene.multisat_agile_eos.bsk_models import fsw as fsw_feedback
+from bsk_rl.scene.multisat_agile_eos.bsk_models import fsw_steering
 from bsk_rl.utilities.initial_conditions import leo_initial_conditions
 
 

deprecated/environments/multisat_agile_eos/gym_env.py

@@ -5,8 +5,8 @@
 from Basilisk.utilities import macros as mc
 from gymnasium import spaces
 
-from bsk_rl.env.multisat_agile_eos import env_settings
-from bsk_rl.env.multisat_agile_eos.bsk_sim import MultiSatAgileEOSSimulator
+from bsk_rl.scene.multisat_agile_eos import env_settings
+from bsk_rl.scene.multisat_agile_eos.bsk_sim import MultiSatAgileEOSSimulator
 
 gym.utils.passive_env_checker.logger.setLevel(
     40

deprecated/environments/multisensor_eos/gym_env.py

@@ -4,8 +4,8 @@
 import numpy as np
 from gymnasium import spaces
 
-from bsk_rl.env.multisensor_eos.bsk_sim import MultiSensorEOSSimulator
-from bsk_rl.env.multisensor_eos.env_settings import Settings
+from bsk_rl.scene.multisensor_eos.bsk_sim import MultiSensorEOSSimulator
+from bsk_rl.scene.multisensor_eos.env_settings import Settings
 
 
 class MultiSensorEOS(gym.Env):

deprecated/environments/simple_eos/gym_env.py

@@ -3,7 +3,7 @@
 from Basilisk.utilities import macros as mc
 from gymnasium import spaces
 
-from bsk_rl.env.simple_eos import bsk_sim
+from bsk_rl.scene.simple_eos import bsk_sim
 
 
 class SimpleEOS(gym.Env):

deprecated/environments/small_body_science/gym_env.py

@@ -2,7 +2,7 @@
 import numpy as np
 from gymnasium import spaces
 
-from bsk_rl.env.small_body_science.bsk_sim import SmallBodyScienceSimulator
+from bsk_rl.scene.small_body_science.bsk_sim import SmallBodyScienceSimulator
 
 
 class SmallBodyScience(gym.Env):

deprecated/environments/small_body_science_pomdp/bsk_sim.py

@@ -5,7 +5,7 @@
 from Basilisk.utilities import macros as mc
 from Basilisk.utilities import orbitalMotion, unitTestSupport
 
-from bsk_rl.env.small_body_science.bsk_sim import SmallBodyScienceSimulator
+from bsk_rl.scene.small_body_science.bsk_sim import SmallBodyScienceSimulator
 
 
 class SmallBodySciencePOMDPSimulator(SmallBodyScienceSimulator):

deprecated/environments/small_body_science_pomdp/gym_env.py

@@ -2,8 +2,8 @@
 import numpy as np
 from gymnasium import spaces
 
-from bsk_rl.env.small_body_science.gym_env import SmallBodyScience
-from bsk_rl.env.small_body_science_pomdp.bsk_sim import SmallBodySciencePOMDPSimulator
+from bsk_rl.scene.small_body_science.gym_env import SmallBodyScience
+from bsk_rl.scene.small_body_science_pomdp.bsk_sim import SmallBodySciencePOMDPSimulator
 
 
 class SmallBodySciencePOMDP(SmallBodyScience):

deprecated/examples/mcts/network_validation_multiprocessing.py

@@ -6,7 +6,7 @@
 import gymnasium as gym
 import numpy as np
 
-from bsk_rl.env.agile_eos.gym_env import AgileEOS  # noqa: F401; needed for gym
+from bsk_rl.scene.agile_eos.gym_env import AgileEOS  # noqa: F401; needed for gym
 
 os.environ["CUDA_VISIBLE_DEVICES"] = "-1"
 

docs/Makefile

@@ -20,7 +20,7 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 clean:
-	rm -rf "source/Examples" "source/API Reference"
+	rm -rf "source/examples" "source/api_reference" "build"
 
 
 view:

docs/build/doctrees/nbsphinx/README.txt

@@ -0,0 +1,3 @@
+This directory includes executed copies of example notebooks so that they do not have to
+run on GitHub actions. To generate these, build the docs locally by running `make html`
+from the `docs` directory.