Finished quick start docs

JuliaAstro · Mar 27, 2024 · 95f6722 · 95f6722
1 parent 24f0a3e
commit 95f6722
Show file tree

Hide file tree

Showing 6 changed files with 123 additions and 17 deletions.
diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -3,6 +3,8 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 HorizonsAPI = "c15253bb-5e94-4b8b-9a02-579bb6c8e3ce"
 HorizonsEphemeris = "05ee1981-f730-42d8-b713-4f42d99733dc"
 MultiDocumenter = "87ed4bf0-c935-4a67-83c3-2a03bee4197c"
+PlotlyJS = "f0f68f2c-4968-5e81-91da-67840de0976a"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 SPICE = "5bab7191-041a-5c2e-a744-024b9c3a5062"
 SPICEApplications = "e12e0822-0612-48d4-a4bb-92984dd6b6ec"
 SPICEBodies = "19f1efb6-7162-484a-b3a1-b52c391689d7"

diff --git a/docs/make.jl b/docs/make.jl
@@ -5,8 +5,8 @@ makedocs(
     format = Documenter.HTML(),
     pages = [
         "Overview" => [
-            "Home" => "index.md",
-            "Getting Started" => "getting-started/index.md",
+            "About Ephemeris" => "index.md",
+            "Quick Start" => "quick-start/index.md",
             "Examples" => "examples/index.md",
         ],
     ],
@@ -56,20 +56,20 @@ content = [
 
 outpath = joinpath(@__DIR__, "build")
 
-MultiDocumenter.make(
-    outpath,
-    content;
-    rootpath = outpath,
-    prettyurls = true,
-    search_engine = MultiDocumenter.SearchConfig(
-        index_versions = ["stable", "dev"],
-        engine = MultiDocumenter.FlexSearch,
-    ),
-    brand_image = MultiDocumenter.BrandImage(
-        "https://loopy.codes",
-        "https://loopy.codes/blog/posts/modeling-with-ephemeris/ephemeris.png",
-    ),
-)
+# MultiDocumenter.make(
+#     outpath,
+#     content;
+#     rootpath = outpath,
+#     prettyurls = true,
+#     search_engine = MultiDocumenter.SearchConfig(
+#         index_versions = ["stable", "dev"],
+#         engine = MultiDocumenter.FlexSearch,
+#     ),
+#     brand_image = MultiDocumenter.BrandImage(
+#         "https://loopy.codes",
+#         "https://loopy.codes/blog/posts/modeling-with-ephemeris/ephemeris.png",
+#     ),
+# )
 
 Documenter.deploydocs(
     target = outpath,

diff --git a/docs/src/getting-started/index.md b/docs/src/getting-started/index.md
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,49 @@
+# About Ephemeris
+
+The positions, velocities, and other attributes of physical objects in our
+solar system are tracked by professionals around the world. NASA maintains two
+sources for solar system ephemeris data: the
+[HORIZONS](https://ssd.jpl.nasa.gov/horizons/) platform, and
+[Generic SPICE Kernels](https://naif.jpl.nasa.gov/pub/naif/generic_kernels/)
+updated (roughly) daily.
+
+## JPL HORIZONS
+
+HORIZONS allows for querying ephemeris for specific bodies at specific time
+points through a REST interface, a graphical web interface, a `telnet`
+command-line interface, and an email interface. Students commonly use the
+graphical web interface, but programmatically fetching and processing ephemeris
+data is useful for more formal and replicable analysis. The open-source packages
+below allow for programmatic and interactive ephemeris fetching from the
+JPL HORIZONS ephemeris platform. Packages marked **external** are not affiliated
+with [`ephemeris.loopy.codes`](index.md).
+
+| Package                                                                  | Description                                                        | Location     |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------ |
+| [`HorizonsAPI.jl`](https://github.com/cadojo/HorizonsAPI.jl)             | A precise JPL HORIZONS REST API client implementation.             |              |
+| [`HorizonsEphemeris.jl`](https://github.com/cadojo/HorizonsEphemeris.jl) | Convenience wrappers around the JPL HORIZONS REST API.             |              |
+| [`Horizons.jl`](https://github.com/PerezHz/HORIZONS.jl)                  | Functions for spawning the `telnet` interface, and querying files. | **external** |
+
+## SPICE Toolkit
+
+SPICE data is packaged in binary files referred to as
+_kernels_. Kernel data can be parsed and processed with JPL's
+[`CSPICE`](https://naif.jpl.nasa.gov/naif/toolkit.html) library. Users of the
+Julia Programming Language can call `CSPICE` routines from within Julia with
+[`SPICE.jl`](https://github.com/JuliaAstro/SPICE.jl).
+
+| Package                                                                       | Description                                                                                             | Location     |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------ |
+| [`SPICEKernels.jl`](https://github.com/cadojo/SPICEKernels.jl)                | All [generic kernels](https://naif.jpl.nasa.gov/naif/data_generic.html) exported as variable constants. |              |
+| [`SPICEBodies.jl`](https://github.com/cadojo/SPICEBodies.jl)                  | Idiomatic wrappers around SPICE and [`SPICE.jl`](https://github.com/JuliaAstro/SPICE.jl) methods.       |              |
+| [`SPICEApplications.jl`](https://github.com/cadojo/SPICEApplications.jl)      | Function interfaces to the SPICE Toolkit executables from within Julia.                                 |              |
+| [`SPICE.jl`](https://github.com/JuliaAstro/SPICE.jl)                          | A Julia interface to the `CSPICE` library provided by NASA JPL.                                         | **external** |
+| [`Ephemerides.jl`](https://github.com/JuliaSpaceMissionDesign/Ephemerides.jl) | Ephemeris kernel reading and interpolation in pure Julia.                                               | **external** |
+
+## Getting Started
+
+These two ephemeris platforms — HORIZONS and SPICE — are both free to use,
+and have been incredibly helpful to students and researchers around the world.
+The Julia packages above — and others — available to help you fetch and parse
+ephemeris data. For more information on how to use these packages, continue on
+to [**Quick Start**](quick-start/index.md).
diff --git a/docs/src/quick-start/index.md b/docs/src/quick-start/index.md
@@ -0,0 +1,56 @@
+# Quick Start
+
+Navigating ephemeris platforms — and processing ephemeris data — can sometimes
+have a steep learning curve. This page will help you get up and running with
+loading and plotting ephemeris. For more detailed information, check out the
+documentation [**examples**](../examples/index.md), or documentation pages
+for each individual package in the drop-down menu.
+
+The `SPICEBodies.KernelBody` type allows us to idiomatically query information
+from the SPICE kernel pool. First, download some common generic kernels (such as
+`de432s` below) and load them into the kernel pool with `SPICE.furnsh`. If you
+want more information about what's in each kernel, inspect each kernel's
+docstring; for example, `@doc de432s`, or `help?> de432s` in Julia's REPL.
+
+```@repl quickstart
+using SPICE, SPICEKernels, SPICEBodies
+
+return furnsh(
+    de432s(),                   # position and velocity data for nearby planets
+    latest_leapseconds_lsk(),   # timekeeping, parsing epochs
+    gm_de440(),                 # mass parameters for major solar system bodies
+    pck00011(),                 # physical properties of major solar system bodies
+)
+
+earth = KernelBody("earth")
+```
+
+We can now call the `earth` variable like a function of time, and get back the
+positions (and velocities) interpolated by `CSPICE` from the data in the kernel
+pool.
+
+```@repl quickstart
+using Dates
+
+timepoints = [DateTime(year, month, 1) for year in 1950:2049, month in 1:12]
+
+states = earth.(timepoints)
+```
+
+Finally, let's plot the data we just collected. This is why we need leap days!
+
+```@repl quickstart
+using Plots
+
+figure = let x = [u[begin] for u in states], y = [u[begin+1] for u in states]
+    scatter(
+        x, y;
+        label=nothing, color=:black, xlabel="X (KM)", ylabel="Y (KM)",
+        title="Earth's Position w.r.t. the Solar System Barycenter"
+    )
+end;
+```
+
+```@example quickstart
+figure # hide
+```