Scrape examples for docs and quicken the CI (#345)

Author: ChristopherRabotin

.github/workflows/deploy-live-docs.yml

@@ -0,0 +1,50 @@
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on merge
+'on':
+  push:
+    branches:
+      - master
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: nightly
+      - run: cargo doc --no-deps --examples -Z rustdoc-scrape-examples
+      - name: Copy plots directories
+        run: |
+          declare -A example_map
+          example_map["01_orbit_prop"]="01_orbit_prop"
+          example_map["02_jwst"]="02_jwst_covar_monte_carlo"
+          
+          declare -A special_cases
+          special_cases["03_geo_analysis"]="03_geo_raise 03_geo_drift 03_geo_sk"
+          
+          for example_dir in examples/*; do
+            example_name=$(basename $example_dir)
+            if [ -d "$example_dir/plots" ]; then
+              if [ -n "${example_map[$example_name]}" ]; then
+                doc_name=${example_map[$example_name]}
+                mkdir -p target/doc/$doc_name/plots
+                cp -r $example_dir/plots/* target/doc/$doc_name/plots/
+              elif [ -n "${special_cases[$example_name]}" ]; then
+                for target_folder in ${special_cases[$example_name]}; do
+                  mkdir -p target/doc/$target_folder/plots
+                  cp -r $example_dir/plots/* target/doc/$target_folder/plots/
+                done
+              else
+                echo "No mapping found for $example_name"
+              fi
+            fi
+          done
+      - uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_NYX_SPACE }}'
+          channelId: live
+          projectId: nyx-space

.github/workflows/deploy-staging-docs.yml

@@ -0,0 +1,47 @@
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on PR
+'on': pull_request
+jobs:
+  build_and_preview:
+    if: '${{ github.event.pull_request.head.repo.full_name == github.repository }}'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: nightly
+      - run: cargo doc --no-deps --examples -Z rustdoc-scrape-examples
+      - name: Copy plots directories
+        run: |
+          declare -A example_map
+          example_map["01_orbit_prop"]="01_orbit_prop"
+          example_map["02_jwst"]="02_jwst_covar_monte_carlo"
+          
+          declare -A special_cases
+          special_cases["03_geo_analysis"]="03_geo_raise 03_geo_drift 03_geo_sk"
+          
+          for example_dir in examples/*; do
+            example_name=$(basename $example_dir)
+            if [ -d "$example_dir/plots" ]; then
+              if [ -n "${example_map[$example_name]}" ]; then
+                doc_name=${example_map[$example_name]}
+                mkdir -p target/doc/$doc_name/plots
+                cp -r $example_dir/plots/* target/doc/$doc_name/plots/
+              elif [ -n "${special_cases[$example_name]}" ]; then
+                for target_folder in ${special_cases[$example_name]}; do
+                  mkdir -p target/doc/$target_folder/plots
+                  cp -r $example_dir/plots/* target/doc/$target_folder/plots/
+                done
+              else
+                echo "No mapping found for $example_name"
+              fi
+            fi
+          done
+      - uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_NYX_SPACE }}'
+          projectId: nyx-space

.github/workflows/firebase-hosting-merge.yml

@@ -83,11 +83,11 @@ jobs:
 
       - name: Run examples
         run: |
-          cargo run --example 01_orbit_prop --release
-          cargo run --example 02_jwst --release
-          cargo run --example 03_geo_drift --release
-          cargo run --example 03_geo_raise --release
-          cargo run --example 03_geo_sk --release
+          cargo build --example 01_orbit_prop --release
+          cargo build --example 02_jwst --release
+          cargo build --example 03_geo_drift --release
+          cargo build --example 03_geo_raise --release
+          cargo build --example 03_geo_sk --release
 
   lints:
     name: Lints

.github/workflows/firebase-hosting-pull-request.yml

@@ -98,22 +98,30 @@ name = "nyx_space"
 linker = "/usr/bin/clang"
 rustflags = ["-Clink-arg=-fuse-ld=lld", "-Clink-arg=-Wl,--no-rosegment"]
 
+[package.metadata.docs.rs]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
+
 [[example]]
 name = "01_orbit_prop"
 path = "examples/01_orbit_prop/main.rs"
+doc-scrape-examples = true
 
 [[example]]
 name = "02_jwst"
 path = "examples/02_jwst_covar_monte_carlo/main.rs"
+doc-scrape-examples = true
 
 [[example]]
 name = "03_geo_drift"
 path = "examples/03_geo_analysis/drift.rs"
+doc-scrape-examples = true
 
 [[example]]
 name = "03_geo_raise"
 path = "examples/03_geo_analysis/raise.rs"
+doc-scrape-examples = true
 
 [[example]]
 name = "03_geo_sk"
 path = "examples/03_geo_analysis/stationkeeping.rs"
+doc-scrape-examples = true

.github/workflows/rust.yaml

@@ -28,10 +28,10 @@ The force models used here are akin to STK's "HPOP" propagator. Specifically, th
 
 In two body propagation, all orbital elements remain constant apart from the true anomaly. In real life, the oblateness of the Earth causes the right ascension of the ascending node to drift with time (red line below). The other force models also affect the overall orbit.
 
-![RAAN, AOP, INC over time](./cubesat-angles-v-time.png)
+![RAAN, AOP, INC over time](./plots/cubesat-angles-v-time.png)
 
-![SMA (km) over time](./cubesat-sma-v-time.png)
+![SMA (km) over time](./plots/cubesat-sma-v-time.png)
 
-![ECC over time](./cubesat-ecc-v-time.png)
+![ECC over time](./plots/cubesat-ecc-v-time.png)
 
 _Note_: These plots were generated with an SRP area of that was ten times larger than the correct value, hence you may notice slightly different Keplerian orbital elements, notably for the change in the shape of the orbit.

Cargo.toml

@@ -1,3 +1,4 @@
+#![doc = include_str!("./README.md")]
 extern crate log;
 extern crate nyx_space as nyx;
 extern crate pretty_env_logger as pel;

examples/01_orbit_prop/README.md

@@ -1,3 +1,4 @@
+#![doc = include_str!("./README.md")]
 extern crate log;
 extern crate nyx_space as nyx;
 extern crate pretty_env_logger as pel;

examples/01_orbit_prop/main.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("./README.md")]
 extern crate log;
 extern crate nyx_space as nyx;
 extern crate pretty_env_logger as pel;

examples/01_orbit_prop/cubesat-angles-v-time.png renamed to examples/01_orbit_prop/plots/cubesat-angles-v-time.png

@@ -1,3 +1,4 @@
+#![doc = include_str!("./README.md")]
 extern crate log;
 extern crate nyx_space as nyx;
 extern crate pretty_env_logger as pel;

examples/01_orbit_prop/cubesat-ecc-v-time.png renamed to examples/01_orbit_prop/plots/cubesat-ecc-v-time.png

@@ -1,3 +1,4 @@
+#![doc = include_str!("./README.md")]
 extern crate log;
 extern crate nyx_space as nyx;
 extern crate pretty_env_logger as pel;

examples/01_orbit_prop/cubesat-sma-v-time.png renamed to examples/01_orbit_prop/plots/cubesat-sma-v-time.png

@@ -41,7 +41,7 @@ pub struct OrbitalDynamics {
 }
 
 impl OrbitalDynamics {
-    /// Initialize point mass dynamics given the EXB IDs and a Cosm
+    /// Initializes the point masses gravities with the provided list of bodies
     pub fn point_masses(celestial_objects: Vec<i32>) -> Self {
         // Create the point masses
         Self::new(vec![PointMasses::new(celestial_objects)])
@@ -176,15 +176,15 @@ pub struct PointMasses {
 }
 
 impl PointMasses {
-    /// Initializes the multibody point mass dynamics with the provided list of bodies
+    /// Initializes the point masses gravities with the provided list of bodies
     pub fn new(celestial_objects: Vec<i32>) -> Arc<Self> {
         Arc::new(Self {
             celestial_objects,
             correction: None,
         })
     }
 
-    /// Initializes the multibody point mass dynamics with the provided list of bodies, and accounting for some light time correction
+    /// Initializes the point masses gravities with the provided list of bodies, and accounting for some light time correction
     pub fn with_correction(celestial_objects: Vec<i32>, correction: Aberration) -> Self {
         Self {
             celestial_objects,

examples/02_jwst_covar_monte_carlo/main.rs

@@ -358,7 +358,7 @@ where
         let mut utc_epoch = StringBuilder::new();
         let mut idx_col = Int32Builder::new();
         for (sno, s) in all_states.iter().enumerate() {
-            utc_epoch.append_value(&s.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
+            utc_epoch.append_value(s.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
 
             // Copy this a bunch of times because all columns must have the same length
             idx_col.append_value(run_indexes[sno]);

examples/03_geo_analysis/drift.rs

@@ -235,7 +235,7 @@ where
         // Epochs
         let mut utc_epoch = StringBuilder::new();
         for s in &states {
-            utc_epoch.append_value(&s.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
+            utc_epoch.append_value(s.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
         }
         record.push(Arc::new(utc_epoch.finish()));
 
@@ -459,7 +459,7 @@ where
         // Epochs (both match for self and others)
         let mut utc_epoch = StringBuilder::new();
         for s in &self_states {
-            utc_epoch.append_value(&s.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
+            utc_epoch.append_value(s.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
         }
         record.push(Arc::new(utc_epoch.finish()));
 

examples/03_geo_analysis/raise.rs

@@ -140,7 +140,7 @@ where
         // Epochs
         let mut utc_epoch = StringBuilder::new();
         for m in &measurements {
-            utc_epoch.append_value(&m.1.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
+            utc_epoch.append_value(m.1.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
         }
         record.push(Arc::new(utc_epoch.finish()));
 

examples/03_geo_analysis/stationkeeping.rs

@@ -287,7 +287,7 @@ where
         // Epochs
         let mut utc_epoch = StringBuilder::new();
         for s in &estimates {
-            utc_epoch.append_value(&s.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
+            utc_epoch.append_value(s.epoch().to_time_scale(TimeScale::UTC).to_isoformat());
         }
         record.push(Arc::new(utc_epoch.finish()));
 

src/dynamics/orbital.rs

@@ -294,8 +294,8 @@ impl TrackingArcSim<Spacecraft, RangeDoppler, GroundStation> {
     /// 5. Build each of these as "tracking strands" for this tracking device.
     /// 6. Organize all of the built tracking strands chronologically.
     /// 7. Iterate through all of the strands:
-    /// 7.a. if that tracker is marked as `Greedy` and it ends after the start of the next strand, change the start date of the next strand.
-    /// 7.b. if that tracker is marked as `Eager` and it ends after the start of the next strand, change the end date of the current strand.
+    ///    7.a. if that tracker is marked as `Greedy` and it ends after the start of the next strand, change the start date of the next strand.
+    ///    7.b. if that tracker is marked as `Eager` and it ends after the start of the next strand, change the end date of the current strand.
     pub fn generate_schedule(
         &self,
         almanac: Arc<Almanac>,

src/mc/results.rs

@@ -171,9 +171,9 @@ impl ErrorCtrl for RSSStep {
 /// > This is a more stringent error control method than [`rss_step`] that is often used as the default in other software such as STK.
 /// > If you set [the] accuracy to a very small number, 1e-13 for example, and set the error control to [`rss_step`], integrator
 /// > performance will be poor, for little if any improvement in the accuracy of the orbit integration.
-/// For more best practices of these integrators (which clone those in GMAT), please refer to the
-/// [GMAT reference](https://github.com/ChristopherRabotin/GMAT/blob/37201a6290e7f7b941bc98ee973a527a5857104b/doc/help/src/Resource_NumericalIntegrators.xml#L1292).
-/// (Source)[https://github.com/ChristopherRabotin/GMAT/blob/37201a6290e7f7b941bc98ee973a527a5857104b/src/base/forcemodel/ODEModel.cpp#L3004]
+/// > For more best practices of these integrators (which clone those in GMAT), please refer to the
+/// > [GMAT reference](https://github.com/ChristopherRabotin/GMAT/blob/37201a6290e7f7b941bc98ee973a527a5857104b/doc/help/src/Resource_NumericalIntegrators.xml#L1292).
+/// > (Source)[https://github.com/ChristopherRabotin/GMAT/blob/37201a6290e7f7b941bc98ee973a527a5857104b/src/base/forcemodel/ODEModel.cpp#L3004]
 #[derive(Clone, Copy)]
 #[allow(clippy::upper_case_acronyms)]
 pub struct RSSState;