From cfeafcf4e06cc2876fda240007fa3cc397a2fc29 Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 2 Aug 2024 16:55:32 -0600 Subject: [PATCH] Scrape examples for docs and quicken the CI (#345) --- .github/workflows/deploy-live-docs.yml | 50 ++++++++++++++++++ .github/workflows/deploy-staging-docs.yml | 47 ++++++++++++++++ .github/workflows/firebase-hosting-merge.yml | 24 --------- .../firebase-hosting-pull-request.yml | 21 -------- .github/workflows/rust.yaml | 10 ++-- Cargo.toml | 8 +++ examples/01_orbit_prop/README.md | 6 +-- examples/01_orbit_prop/main.rs | 1 + .../{ => plots}/cubesat-angles-v-time.png | Bin .../{ => plots}/cubesat-ecc-v-time.png | Bin .../{ => plots}/cubesat-sma-v-time.png | Bin examples/02_jwst_covar_monte_carlo/main.rs | 1 + examples/03_geo_analysis/drift.rs | 1 + examples/03_geo_analysis/raise.rs | 1 + examples/03_geo_analysis/stationkeeping.rs | 1 + src/dynamics/orbital.rs | 6 +-- src/mc/results.rs | 2 +- src/md/trajectory/traj.rs | 4 +- src/od/msr/arc.rs | 2 +- src/od/process/export.rs | 2 +- src/od/simulator/arc.rs | 4 +- src/propagators/error_ctrl.rs | 6 +-- 22 files changed, 131 insertions(+), 66 deletions(-) create mode 100644 .github/workflows/deploy-live-docs.yml create mode 100644 .github/workflows/deploy-staging-docs.yml delete mode 100644 .github/workflows/firebase-hosting-merge.yml delete mode 100644 .github/workflows/firebase-hosting-pull-request.yml rename examples/01_orbit_prop/{ => plots}/cubesat-angles-v-time.png (100%) rename examples/01_orbit_prop/{ => plots}/cubesat-ecc-v-time.png (100%) rename examples/01_orbit_prop/{ => plots}/cubesat-sma-v-time.png (100%) diff --git a/.github/workflows/deploy-live-docs.yml b/.github/workflows/deploy-live-docs.yml new file mode 100644 index 00000000..9f5d038b --- /dev/null +++ b/.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 diff --git a/.github/workflows/deploy-staging-docs.yml b/.github/workflows/deploy-staging-docs.yml new file mode 100644 index 00000000..f551e641 --- /dev/null +++ b/.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 diff --git a/.github/workflows/firebase-hosting-merge.yml b/.github/workflows/firebase-hosting-merge.yml deleted file mode 100644 index ee9401d0..00000000 --- a/.github/workflows/firebase-hosting-merge.yml +++ /dev/null @@ -1,24 +0,0 @@ -# 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: stable - - run: cargo doc --no-deps - - uses: FirebaseExtended/action-hosting-deploy@v0 - with: - repoToken: '${{ secrets.GITHUB_TOKEN }}' - firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_NYX_SPACE }}' - channelId: live - projectId: nyx-space diff --git a/.github/workflows/firebase-hosting-pull-request.yml b/.github/workflows/firebase-hosting-pull-request.yml deleted file mode 100644 index 08990801..00000000 --- a/.github/workflows/firebase-hosting-pull-request.yml +++ /dev/null @@ -1,21 +0,0 @@ -# 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: stable - - run: cargo doc --no-deps - - uses: FirebaseExtended/action-hosting-deploy@v0 - with: - repoToken: '${{ secrets.GITHUB_TOKEN }}' - firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_NYX_SPACE }}' - projectId: nyx-space diff --git a/.github/workflows/rust.yaml b/.github/workflows/rust.yaml index ae945ff4..8434d6ee 100644 --- a/.github/workflows/rust.yaml +++ b/.github/workflows/rust.yaml @@ -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 diff --git a/Cargo.toml b/Cargo.toml index 199f0cd7..7fc9b2b6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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 diff --git a/examples/01_orbit_prop/README.md b/examples/01_orbit_prop/README.md index 3ff583e2..4901f067 100644 --- a/examples/01_orbit_prop/README.md +++ b/examples/01_orbit_prop/README.md @@ -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. diff --git a/examples/01_orbit_prop/main.rs b/examples/01_orbit_prop/main.rs index 0667f3e2..c2f46b0b 100644 --- a/examples/01_orbit_prop/main.rs +++ b/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; diff --git a/examples/01_orbit_prop/cubesat-angles-v-time.png b/examples/01_orbit_prop/plots/cubesat-angles-v-time.png similarity index 100% rename from examples/01_orbit_prop/cubesat-angles-v-time.png rename to examples/01_orbit_prop/plots/cubesat-angles-v-time.png diff --git a/examples/01_orbit_prop/cubesat-ecc-v-time.png b/examples/01_orbit_prop/plots/cubesat-ecc-v-time.png similarity index 100% rename from examples/01_orbit_prop/cubesat-ecc-v-time.png rename to examples/01_orbit_prop/plots/cubesat-ecc-v-time.png diff --git a/examples/01_orbit_prop/cubesat-sma-v-time.png b/examples/01_orbit_prop/plots/cubesat-sma-v-time.png similarity index 100% rename from examples/01_orbit_prop/cubesat-sma-v-time.png rename to examples/01_orbit_prop/plots/cubesat-sma-v-time.png diff --git a/examples/02_jwst_covar_monte_carlo/main.rs b/examples/02_jwst_covar_monte_carlo/main.rs index 117d2ba3..e6b33a36 100644 --- a/examples/02_jwst_covar_monte_carlo/main.rs +++ b/examples/02_jwst_covar_monte_carlo/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; diff --git a/examples/03_geo_analysis/drift.rs b/examples/03_geo_analysis/drift.rs index 41d6503a..ca590a62 100644 --- a/examples/03_geo_analysis/drift.rs +++ b/examples/03_geo_analysis/drift.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; diff --git a/examples/03_geo_analysis/raise.rs b/examples/03_geo_analysis/raise.rs index 063db4a7..6d7750f7 100644 --- a/examples/03_geo_analysis/raise.rs +++ b/examples/03_geo_analysis/raise.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; diff --git a/examples/03_geo_analysis/stationkeeping.rs b/examples/03_geo_analysis/stationkeeping.rs index 442b5667..ed8ecef1 100644 --- a/examples/03_geo_analysis/stationkeeping.rs +++ b/examples/03_geo_analysis/stationkeeping.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; diff --git a/src/dynamics/orbital.rs b/src/dynamics/orbital.rs index 994abd5a..1358f7b0 100644 --- a/src/dynamics/orbital.rs +++ b/src/dynamics/orbital.rs @@ -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) -> Self { // Create the point masses Self::new(vec![PointMasses::new(celestial_objects)]) @@ -176,7 +176,7 @@ 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) -> Arc { Arc::new(Self { celestial_objects, @@ -184,7 +184,7 @@ impl PointMasses { }) } - /// 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, correction: Aberration) -> Self { Self { celestial_objects, diff --git a/src/mc/results.rs b/src/mc/results.rs index ada9eb1d..68955795 100644 --- a/src/mc/results.rs +++ b/src/mc/results.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]); diff --git a/src/md/trajectory/traj.rs b/src/md/trajectory/traj.rs index e841fe87..04bd5de9 100644 --- a/src/md/trajectory/traj.rs +++ b/src/md/trajectory/traj.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())); diff --git a/src/od/msr/arc.rs b/src/od/msr/arc.rs index 0a700471..13eb5d75 100644 --- a/src/od/msr/arc.rs +++ b/src/od/msr/arc.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())); diff --git a/src/od/process/export.rs b/src/od/process/export.rs index 7520fbf4..2d373d70 100644 --- a/src/od/process/export.rs +++ b/src/od/process/export.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())); diff --git a/src/od/simulator/arc.rs b/src/od/simulator/arc.rs index 6b2aac78..22ea603a 100644 --- a/src/od/simulator/arc.rs +++ b/src/od/simulator/arc.rs @@ -294,8 +294,8 @@ impl TrackingArcSim { /// 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, diff --git a/src/propagators/error_ctrl.rs b/src/propagators/error_ctrl.rs index 19487bb6..13720ed4 100644 --- a/src/propagators/error_ctrl.rs +++ b/src/propagators/error_ctrl.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;