Finished draft of common documentation

.vscode/ltex.dictionary.en-US.txt

@@ -0,0 +1 @@
+ephemeris

docs/Project.toml

@@ -1,4 +1,5 @@
 [deps]
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 HorizonsAPI = "c15253bb-5e94-4b8b-9a02-579bb6c8e3ce"
 HorizonsEphemeris = "05ee1981-f730-42d8-b713-4f42d99733dc"

docs/make.jl

@@ -6,8 +6,10 @@ makedocs(
     pages = [
         "Overview" => [
             "About Ephemeris" => "index.md",
-            "Quick Start" => "quick-start/index.md",
-            "Examples" => "examples/index.md",
+            "Quick Start" => [
+                "SPICE" => "examples/spice/index.md",
+                "HORIZONS" => "examples/horizons/index.md",
+            ],
         ],
     ],
 )

docs/src/examples/horizons/index.md

@@ -0,0 +1,57 @@
+# HORIZONS Ephemeris Examples
+
+The JPL HORIZONS platform provides ephemeris data as Cartesian state vectors,
+osculating orbital elements, and other representations. The precise
+[REST API](https://ssd-api.jpl.nasa.gov/doc/horizons.html)
+accepted by the JPL HORIZONS servers is implemented in Julia with `HorizonsAPI.jl`.
+
+```@repl horizons-examples
+using HorizonsAPI
+
+fetch_vectors(399; format="text") # Earth's position w.r.t. the solar system barycenter
+```
+
+The `CENTER` parameter specifies the ephemeris reference position.
+
+```@repl horizons-examples
+fetch_vectors(499; format="text", CENTER="@399") # Mars' position w.r.t. Earth
+```
+
+The response from the HORIZONS API contains a lot of information! To more simply
+fetch and inspect ephemeris data from JPL HORIZONS servers, use the `ephemeris`
+method in `HorizonsEphemeris.jl`.
+
+```@repl horizons-examples
+using Dates, HorizonsEphemeris
+
+ephemeris("earth", now())
+```
+
+The output of `ephemeris` is a `NamedTuple`, so you can easily pass it along to
+`DataFrames.jl` for convenient inspection & data processing. Note the `wrt`
+keyword argument as well; it is a simplified interface to the HORIZONS API
+`CENTER` argument.
+
+```@repl horizons-examples
+using DataFrames
+
+data = DataFrame(
+    ephemeris("earth", now() - Year(50), now() + Year(5), Day(1); wrt="jupiter")
+)
+```
+
+This example wouldn't be complete without some plotting!
+
+```@repl horizons-examples
+using Plots
+
+figure = plot(
+    data.x, data.y;
+    xlabel="X (KM)", ylabel="Y (KM)", label=:none,
+    title="Earth's Position w.r.t. Jupiter"
+);
+```
+
+```@example horizons-examples
+figure # hide
+```

docs/src/examples/index.md

@@ -1 +1,8 @@
-# Examples
+# Ephemeris Package Examples
+
+Navigating ephemeris platforms — and processing ephemeris data — can sometimes
+have a steep learning curve. For simple blocks of code to get you up and running
+with loading and plotting ephemeris data, check out the
+[SPICE](spice/index.md) or [HORIZONS](horizons/index.md)
+examples, or the documentation pages for each individual package in the
+drop-down menu above.

docs/src/examples/spice/index.md

@@ -0,0 +1,52 @@
+# SPICE Ephemeris Examples
+
+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(1950,1,1) : Month(1) : DateTime(2049,1,1)
+
+states = earth.(timepoints)
+```
+
+Finally, let's plot the data we just collected.
+
+```@repl quickstart
+using Plots
+
+figure = let x = map(u -> u[begin], states), y = map(u -> u[begin+1], states)
+    scatter(
+        x, y;
+        label=nothing, markersize=1,
+        xlabel="X (KM)", ylabel="Y (KM)", zlabel="Z (KM)",
+        title="Earth's Position w.r.t. SSB",
+        aspect_ratio=1,
+    );
+end
+```
+
+```@example quickstart
+figure # hide
+```

docs/src/index.md

@@ -46,4 +46,4 @@ 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).
+to the documentation [**examples**](examples/index.md).