Merge pull request #841 from AVSLab/feature/doc_updates

Updates to BSK Documentation System
AVSLab · Nov 4, 2024 · 92bc110 · 92bc110
2 parents 55b4127 + bf04376
commit 92bc110
Show file tree

Hide file tree

Showing 11 changed files with 139 additions and 69 deletions.
diff --git a/docs/source/Install/installOptionalPackages.rst b/docs/source/Install/installOptionalPackages.rst
@@ -28,7 +28,7 @@ Creating the Sphinx Basilisk Documentation
 Go to :ref:`createHtmlDocumentation` to learn what associated python tools are required.
 The following python packages must be installed via ``pip``::
 
-    pip3 install 'sphinx>7.0.0, <8.0.0' sphinx_rtd_theme==2.0.0 breathe recommonmark docutils
+    pip3 install sphinx sphinx_rtd_theme breathe recommonmark docutils
 
 See the list at the top of this page for what versions of these packages are acceptable.
 

diff --git a/docs/source/Support/bskReleaseNotes.rst b/docs/source/Support/bskReleaseNotes.rst
@@ -41,7 +41,9 @@ Version  |release|
 - Updated :ref:`scenarioOrbitManeuver` to include a SPICE module that rotates the Earth
 - Changed the way polyhedron gravity is computed to be more computationally efficient
 - Updated :ref:`vizInterface` to flush the output buffer when saving binary files to avoid truncation
-
+- Updated :ref:`examples` to better include folders of scenario tutorial scripts
+- Updated documentation build to use latest version of ``sphinx`` and ``sphinx_rtd_theme``.
+  Updated the install documenation and optional package requirements.
 
 Version 2.5.0 (Sept. 30, 2024)
 ------------------------------

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -76,7 +76,17 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = [
+    'examples/BskSim/scenarios/index.rst',
+    'examples/BskSim/index.rst',
+    'examples/MultiSatBskSim/scenariosMultiSat/index.rst',
+    'examples/MultiSatBskSim/index.rst',
+    'examples/OpNavScenarios/scenariosOpNav/index.rst',
+    'examples/OpNavScenarios/scenariosOpNav/CNN_ImageGen/index.rst',
+    'examples/OpNavScenarios/scenariosOpNav/OpNavMC/index.rst',
+    'examples/OpNavScenarios/index.rst',
+    'examples/MonteCarloExamples/index.rst'
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
@@ -94,7 +104,6 @@
 # documentation.
 html_theme_options = {
     'logo_only': False,
-    'display_version': True,
     'prev_next_buttons_location': 'bottom',
     'style_external_links': True,
     'vcs_pageview_mode': '',

diff --git a/examples/BskSim/scenarios/scenario_AttGuidHyperbolic.py b/examples/BskSim/scenarios/scenario_AttGuidHyperbolic.py
@@ -28,7 +28,7 @@
       python3 scenario_AttGuidHyperbolic.py
 
 
-The simulation mimics the basic simulation simulation in the earlier tutorial in
+The simulation mimics the basic simulation in the earlier tutorial in
 :ref:`scenarioAttGuideHyperbolic`.
 
 The simulation layout is shown in the following illustration.
@@ -50,8 +50,7 @@
 
 The advantage of the BSK_Sim architecture becomes apparent here. All modules and setup required for the MRP Feedback task
 were already defined from an earlier scenario. The user simply adds the preconfigured task to the event without
-having to manually reconfigure the messages. Now there is an additional FSW mode available for all current and
-future :ref:`Folder_BskSim` files.
+having to manually reconfigure the messages. Now there is an additional FSW mode available for all ``bskSim()`` files.
 
 Illustration of Simulation Results
 ----------------------------------

diff --git a/examples/BskSim/scenarios/scenario_AttGuidance.py b/examples/BskSim/scenarios/scenario_AttGuidance.py
@@ -29,7 +29,7 @@
 
       python3 scenario_AttGuidance.py
 
-The simulation mimics the basic simulation simulation in the earlier tutorial in
+The simulation mimics the basic simulation in the earlier tutorial in
 :ref:`scenarioAttitudeGuidance`.
 
 
@@ -55,13 +55,13 @@
 (``mrpFeedbackRWConfig()``, ``attTrackingErrorConfig()``, ``rwMotorTorqueConfig()``). The only remaining
 module is the hill pointing module itself which is set within ``__init__()``.
 
-These modules provide the initial setup for an attitude guidance system that makes use of an hill
+These modules provide the initial setup for an attitude guidance system that makes use of a hill
 pointing model, a module
 that tracks the error of the spacecraft's MRP parameters against the vector pointing towards the central, planetary
 body, and uses a module that takes that information to provide a torque to correct for the error.
 
-This event is triggered when a user calls `self.masterSim.modeRequest = 'hillPoint'` in any
-current or future :ref:`Folder_BskSim` file.
+This event is triggered when a user calls `self.modeRequest = 'hillPoint'` in any
+of file.
 
 Illustration of Simulation Results
 ----------------------------------

diff --git a/examples/BskSim/scenarios/scenario_AttSteering.py b/examples/BskSim/scenarios/scenario_AttSteering.py
@@ -28,7 +28,7 @@
 
       python3 scenario_AttSteering.py
 
-The simulation mimics the basic simulation simulation in the earlier tutorial in
+The simulation mimics the basic simulation in the earlier tutorial in
 :ref:`scenarioAttitudeSteering`.
 
 The simulation layout is shown in the following illustration.

diff --git a/examples/BskSim/scenarios/scenario_FeedbackRW.py b/examples/BskSim/scenarios/scenario_FeedbackRW.py
@@ -35,7 +35,7 @@
       python3 scenario_FeedbackRW.py
 
 
-The simulation mimics the basic simulation simulation in the earlier tutorial in
+The simulation mimics the basic simulation in the earlier tutorial in
 :ref:`scenarioAttitudeFeedbackRW`.
 The simulation layout is shown in the following illustration.
 

diff --git a/examples/BskSim/scenarios/scenario_LambertGuidance.py b/examples/BskSim/scenarios/scenario_LambertGuidance.py
@@ -57,9 +57,9 @@
 
 The five Lambert modules were added to the :ref:`BSK_FSW` framework.
 
-The first maneuver event is triggered when a user calls `self.masterSim.modeRequest = 'lambertFirstDV'` in any
-current or future :ref:`Folder_BskSim` file, and the second maneuver using
-`self.masterSim.modeRequest = 'lambertSecondDV'`
+The first maneuver event is triggered when a user calls `self.modeRequest = 'lambertFirstDV'` in any
+``bskSim()`` simulation, and the second maneuver using
+`self.modeRequest = 'lambertSecondDV'`
 
 Illustration of Simulation Results
 ----------------------------------

diff --git a/examples/OpNavScenarios/modelsOpNav/BSK_OpNavDynamics.py b/examples/OpNavScenarios/modelsOpNav/BSK_OpNavDynamics.py
@@ -19,7 +19,7 @@
 Overview
 --------
 
-``OpNavScenarios/models/BSK_OpNavDynamics.py`` is similar to the :ref:`Folder_BskSim` versions seen previously.
+``OpNavScenarios/models/BSK_OpNavDynamics.py`` is similar to the ``bskSim()`` versions seen previously.
 The main additions are
 the instantiation of :ref:`vizInterface`, and the camera module.
 

diff --git a/examples/_default.rst b/examples/_default.rst
@@ -32,7 +32,6 @@ Orbital Simulations
    Defining Motion Relative to Planet <scenarioCentralBody>
    Simulating Trajectory about Multiple Celestial Bodies <scenarioPatchedConics>
    Including Custom Gravitational Bodies <scenarioCustomGravBody>
-   Small Body Waypoint-to-Waypoint Control <scenarioSmallBodyFeedbackControl>
    Near-Halo Orbit Simulation <scenarioHaloOrbit>
 
 
@@ -229,31 +228,114 @@ Mission Simulations
    Asteroid Arrival <scenarioAsteroidArrival>
    Aerocapture Scenario <scenarioAerocapture>
 
-bskSim()-Based Simulation
--------------------------
+
+
+Spacecraft Formation Flying
+---------------------------
 
 .. toctree::
    :maxdepth: 1
 
+   Basic Servicer/Debris Simulation <scenarioFormationBasic>
+   Mean orbit element based relative motion control <scenarioFormationMeanOEFeedback>
+   Impulsive feedback control of relative motion <scenarioFormationReconfig>
+   Electrostatic Tractor Debris Reorbiting <scenarioDebrisReorbitET>
+   Attitude-Driven differential drag control <scenarioDragRendezvous>
+   Servicer approaching a debris object with 3 flight modes <scenarioRendezVous>
+   Walker-Delta Satellite Constellation <scenarioSatelliteConstellation>
+
+Small Body Navigation Simulations
+---------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+    Proximity Operations Hybrid EKF <scenarioSmallBodyNav>
+    Non-Keplerian Acceleration Estimation using UKF <scenarioSmallBodyNavUKF>
+    Landmarks-based Navigation <scenarioSmallBodyLandmarks>
+
+
+``bskSim()`` Architecture
+-------------------------
+
+Single Satellite
+^^^^^^^^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
 
    Basic Orbital Simulation  <BskSim/scenarios/scenario_BasicOrbit>
-   Attitude Detumble Control  <BskSim/scenarios/scenario_FeedbackRW>
+   Attitude Detumble Control with RW  <BskSim/scenarios/scenario_FeedbackRW>
    Hill Pointing Attitude Control  <BskSim/scenarios/scenario_AttGuidance>
    Velocity Frame Pointing Control  <BskSim/scenarios/scenario_AttGuidHyperbolic>
    MRP Steering Attitude Control  <BskSim/scenarios/scenario_AttSteering>
    Sun Pointing Mode Include Eclipse Evaluation  <BskSim/scenarios/scenario_AttEclipse>
    Alternating FSW Attitude Pointing Modes <BskSim/scenarios/scenario_AttModes>
    Reaction Wheel Fault Scenario Simulation <BskSim/scenarios/scenario_AddRWFault>
    Lambert Guidance Scenario <BskSim/scenarios/scenario_LambertGuidance>
-   bskSim Scenarios Folder <BskSim/index>
+   Attitude Control <BskSim/scenarios/scenario_AttFeedback>
+
+Satellite Formation
+^^^^^^^^^^^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   Two-Spacecraft Formation using BskSim  <BskSim/scenarios/scenario_BasicOrbitFormation>
+   Relative Pointing Control  <BskSim/scenarios/scenario_RelativePointingFormation>
+
+
+Support Files
+"""""""""""""
+
+.. toctree::
+   :maxdepth: 1
+
+   Master File <BskSim/BSK_masters>
+   Models Folder <BskSim/models/index>
+   Plotting Functions <BskSim/plotting/index>
+
+
+
+
+``MultiSatBskSim()`` Architecture
+---------------------------------
+
+Scenarios
+^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   Three-Spacecraft Formation using MultiSat architecture  <MultiSatBskSim/scenariosMultiSat/scenario_BasicOrbitMultiSat>
+   Attitude Guidance Modes Scheduling  <MultiSatBskSim/scenariosMultiSat/scenario_AttGuidMultiSat>
+   Formation Flying Control  <MultiSatBskSim/scenariosMultiSat/scenario_StationKeepingMultiSat>
+
+Support Files
+"""""""""""""
+
+.. toctree::
+   :maxdepth: 1
+
+   Master file <MultiSatBskSim/BSK_MultiSatMasters>
+   Models Folder <MultiSatBskSim/modelsMultiSat/index>
+   Plotting Functions <MultiSatBskSim/plottingMultiSat/index>
+
 
 Optical Navigation Simulations
 ------------------------------
 
+Scenarios
+^^^^^^^^^
+
 .. toctree::
    :maxdepth: 1
+   :numbered:
 
-   BSK OpNav Sim  <OpNavScenarios/BSK_OpNav>
+   BSK OpNav Sim Master File  <OpNavScenarios/BSK_OpNav>
    Hough Circles for Pointing and Orbit Determination  <OpNavScenarios/scenariosOpNav/scenario_OpNavAttOD>
    Limb-based method for Pointing and Orbit Determination  <OpNavScenarios/scenariosOpNav/scenario_OpNavAttODLimb>
    CNN for Pointing and Orbit Determination   <OpNavScenarios/scenariosOpNav/scenario_CNNAttOD>
@@ -263,71 +345,49 @@ Optical Navigation Simulations
    Pointing with Hough Circles  <OpNavScenarios/scenariosOpNav/scenario_OpNavPoint>
    Pointing with Limb-based method   <OpNavScenarios/scenariosOpNav/scenario_OpNavPointLimb>
    Filter Heading measurements  <OpNavScenarios/scenariosOpNav/scenario_OpNavHeading>
-   OpNav Scenarios Folder <OpNavScenarios/index>
 
-Small Body Navigation Simulations
----------------------------------
+Support Files
+"""""""""""""
 
 .. toctree::
    :maxdepth: 1
 
-    Proximity Operations Hybrid EKF <scenarioSmallBodyNav>
-    Non-Keplerian Acceleration Estimation using UKF <scenarioSmallBodyNavUKF>
-    Landmarks-based Navigation <scenarioSmallBodyLandmarks>
-
-Monte Carlo Simulations
------------------------
+   Models Folder <OpNavScenarios/modelsOpNav/index>
+   Plotting Functions <OpNavScenarios/plottingOpNav/index>
 
+CNN Image Generation
+^^^^^^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
 
-   MC run with RW control  <scenarioMonteCarloAttRW>
-   MC run using Python Spice setup  <scenarioMonteCarloSpice>
-   MC run using BSK Sim Framework  <MonteCarloExamples/scenario_AttFeedbackMC>
-   MC rerun using prior MC run parameters  <MonteCarloExamples/scenarioRerunMonteCarlo>
-   MC Plotting using datashaders and bokeh  <MonteCarloExamples/scenarioAnalyzeMonteCarlo>
-   MC example Folder <MonteCarloExamples/index>
-   Sensitivity Analysis of a differential drag spacecraft control <scenarioDragSensitivity>
-
-
-Spacecraft Formation Flying
----------------------------
-
-Stand Alone Architecture
-^^^^^^^^^^^^^^^^^^^^^^^^
+   Monte-Carlo Script to Create Image Set  <OpNavScenarios/scenariosOpNav/CNN_ImageGen/OpNavMonteCarlo>
+   Scenario called by MC Image Generation Script  <OpNavScenarios/scenariosOpNav/CNN_ImageGen/scenario_CNNImages>
 
+CNN Image Generation
+^^^^^^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
 
-   Basic Servicer/Debris Simulation <scenarioFormationBasic>
-   Mean orbit element based relative motion control <scenarioFormationMeanOEFeedback>
-   Impulsive feedback control of relative motion <scenarioFormationReconfig>
-   Electrostatic Tractor Debris Reorbiting <scenarioDebrisReorbitET>
-   Attitude-Driven differential drag control <scenarioDragRendezvous>
-   Servicer approaching a debris object with 3 flight modes <scenarioRendezVous>
-   Walker-Delta Satellite Constellation <scenarioSatelliteConstellation>
+   Monte-Carlo Simulations using a OpNav Scenario  <OpNavScenarios/scenariosOpNav/OpNavMC/MonteCarlo>
+   Optical Limb Tracking Scenario  <OpNavScenarios/scenariosOpNav/OpNavMC/scenario_LimbAttOD>
+   Optical Navitation Scenario  <OpNavScenarios/scenariosOpNav/OpNavMC/scenario_OpNavAttODMC>
 
 
-``FormationBskSim`` Architecture
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Monte Carlo Simulations
+-----------------------
 
 .. toctree::
    :maxdepth: 1
 
-   Two-Spacecraft Formation using BskSim  <BskSim/scenarios/scenario_BasicOrbitFormation>
-   Relative Pointing Control  <BskSim/scenarios/scenario_RelativePointingFormation>
+   MC run with RW control  <scenarioMonteCarloAttRW>
+   MC run using Python Spice setup  <scenarioMonteCarloSpice>
+   MC run using BSK Sim Framework  <MonteCarloExamples/scenario_AttFeedbackMC>
+   MC rerun using prior MC run parameters  <MonteCarloExamples/scenarioRerunMonteCarlo>
+   MC Plotting using datashaders and bokeh  <MonteCarloExamples/scenarioAnalyzeMonteCarlo>
+   Sensitivity Analysis of a differential drag spacecraft control <scenarioDragSensitivity>
 
 
-``MultiSatBskSim`` Architecture
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. toctree::
-   :maxdepth: 1
-
-   Three-Spacecraft Formation using MultiSat architecture  <MultiSatBskSim/scenariosMultiSat/scenario_BasicOrbitMultiSat>
-   Attitude Guidance Modes Scheduling  <MultiSatBskSim/scenariosMultiSat/scenario_AttGuidMultiSat>
-   Formation Flying Control  <MultiSatBskSim/scenariosMultiSat/scenario_StationKeepingMultiSat>
-   MultiSatBskSim Folder <MultiSatBskSim/index>
 
 
 Advanced Simulation Options
@@ -362,4 +422,4 @@ Interfacing with Vizard
 
    Live Streaming to Vizard  <scenarioBasicOrbitStream>
    Pointing a Vizard Camera  <scenarioVizPoint>
-   Convert Simulation Data file to Vizard File <scenarioDataToViz>
+   Convert Simulation Data File to Vizard File <scenarioDataToViz>
diff --git a/requirements_optional.txt b/requirements_optional.txt
@@ -1,7 +1,7 @@
 breathe
 docutils
 recommonmark
-sphinx>7.0.0, <8.0.0
-sphinx_rtd_theme==2.0.0
+sphinx>7.0.0
+sphinx_rtd_theme>=3.0.0
 pre-commit
 clang-format