Merge pull request #17 from JuliaSpaceMissionDesign/10-update-documen…

…tation-examples-to-run-on-repl 10 update documentation examples to run on repl
JuliaSpaceMissionDesign · Dec 3, 2023 · 7f896fb · 7f896fb
2 parents 3dc7f78 + 2717eb2
commit 7f896fb
Show file tree

Hide file tree

Showing 16 changed files with 604 additions and 354 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,17 +1,25 @@
 using Tempo
 using Documenter
 
+const CI = get(ENV, "CI", "false") == "true"
+
 makedocs(;
     authors="Julia Space Mission Design Development Team",
     sitename="Tempo.jl",
     modules=[Tempo],
+    format=Documenter.HTML(; prettyurls=CI, highlights=["yaml"], ansicolor=true),
     pages=[
         "Home" => "index.md",
-        "API" => "api.md",
+
         "Tutorials" => [
             "Epochs" => "tutorials/t01_epochs.md",
-            "Scales" => "tutorials/t02_scales.md"
-        ]
+            "Custom Timescales" => "tutorials/t02_scales.md"
+        ],
+
+        "API" => [
+            "Public API" => "api.md",
+            "Low-level API" => "lapi.md"
+        ],
     ],
 )
 

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -1,29 +1,72 @@
-# API Reference
+# [Public Documentation](@id tempo_api)
 
-## Constants
+## Datetime 
+```@docs 
+Date 
+Time 
+DateTime 
+year 
+month 
+day 
+hour 
+minute
+second
+find_dayinyear
+```
+
+## Epochs 
 
-```@autodocs
-Modules = [Tempo]
-Order = [:constant]
+### Types
+```@docs 
+Epoch 
+timescale
+value
 ```
 
-## Types
+### Origins
+```@docs
+JD
+J2000
+MJD
+MJD2000
+```
 
-```@autodocs
-Modules = [Tempo]
-Order = [:type]
+## Conversions
+```@docs 
+j2000
+j2000s
+j2000c
 ```
 
-## Types
+## Timescales
 
-```@autodocs
-Modules = [Tempo]
-Order = [:function]
+### Time System 
+```@docs 
+@timescale 
+timescale_alias
+timescale_name
+timescale_id
+TimeSystem
+add_timescale!
+TIMESCALES
 ```
 
-## Macros
+### Default Timescales 
+```@docs 
+GPS
+TAI
+TCB
+TCG
+TDB 
+TDBH
+TT
+UT1
+UTC
+```
 
-```@autodocs
-Modules = [Tempo]
-Order = [:macro]
+## Constants 
+```@docs
+DJ2000
+DMJD 
+DJM0
 ```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,93 +1,46 @@
-# Tempo.jl
+# Welcome to Tempo.jl!
 
-_Time transformations in Julia._
+_Efficient Astronomical Time transformations in Julia._
 
-The `Tempo` module is thought to be a fast, efficient and precise time transformation library 
-capable to handle the different transformations needed in the astronomical and astrodynamical 
-application of the `JSMD` ecosystem.
+Tempo.jl is an astronomical library that enables fast, efficient and high-accuracy time transformations between common and user-defined time scales and time representations.
 
-## Overview
+## Installation 
+This package can be installed using Julia's package manager:
+```julia
+julia> import Pkg
 
-There are different ways to represent an epoch within `Tempo`, depending on the specific 
-application. This section is here to help you choose the proper time representation and to 
-present the capabilities of the module in transforming time between different representations.
-
-First of all, there is a deep difference in the way time is thought in the everyday life and 
-when dealing with space-related applications. 
-Whenever we say _the 12:35 of the 1st of January 2023_, we are merging three concepts: 
-the **calendar** (_1st January 2023_) and the **time representation** (_12:35_) together with
-its **scale**.
-
-
-Calculations in any scientific discipline may involve precise time, but what 
-sets astronomy apart is the number and variety of **time scales** that have to be used.
-In fact, in astronomical applications the physical context of the “clock” matters,
-whether it is on Earth, moving or stationary, or on a spacecraft.
-
-```@raw html
-<figure>
-    <img src="https://gitlab.com/astronaut-tools/julia/Documentation/-/raw/390f98f53a0d35a3c0963dff8a5f608ff79304db/docs/src/assets/figures/enciclopedia/timescales.png" alt="Image" width="600" />
-    <figcaption> Time Conversions - The difference in each timescale is shown with 
-    respect to TAI. </figcaption>
-</figure>
+julia> Pkg.add("Tempo.jl");
 ```
 
-The most relevant time scales for these applications are:
-
-- **UT1** (Universal Time 1): UT1 is a time scale based on the rotation of the Earth. 
-    It is used to measure the positions of celestial objects relative to the Earth's 
-    surface. UT1 is closely related to *Greenwich Mean Time (GMT)*, and the two time 
-    scales are often used interchangeably.
-
-- **TAI** (International Atomic Time): TAI is a time scale based on the average 
-    frequency of a set of atomic clocks. It is used to measure the positions of 
-    celestial objects relative to the Earth's surface.
+## Quickstart
+Create an [`Epoch`](@ref): 
+```julia
+# Create an Epoch from an ISO-formatted string
+tai = Epoch("2022-10-02T12:04:23.043 TAI")
 
-- **TT** (Terrestrial Time): TT is a time scale based on the motion of celestial 
-    objects around the solar system barycenter (the center of mass of the solar system). 
-    It is used to measure the positions of celestial objects relative to the Earth's surface.
+# Create an Epoch from a Julian Date
+jd = Epoch("JD 2451545.0")
 
-- **TDB** (Barycentric Dynamical Time): TDB is a time scale based on the motion of 
-    celestial objects around the solar system barycenter (the center of mass of the 
-    solar system). It is used to measure the positions of celestial objects relative 
-    to the solar system barycenter.
-
-- **TCB** (Barycentric Coordinate Time): TCB is a time scale based on the motion of 
-    celestial objects around the solar system barycenter (the center of mass of the 
-    solar system). It is used to measure the positions of celestial objects relative 
-    to the solar system barycenter.
-
-- **TCG** (Geocentric Coordinate Time): TCG is a time scale based on the rotation of 
-    the Earth. It is used to measure the positions of celestial objects relative to the 
-    Earth's surface.
-
-- **Teph** (Ephemeris Time): Teph is a time scale based on the motion of celestial 
-    objects around the solar system barycenter (the center of mass of the solar 
-    system). It is used to measure the positions of celestial objects relative to 
-    the solar system barycenter -- here considered equivalent of _TDB_.
-
-Of the seven time scales to be described here, one is atomic time (TAI), 
-one is solar time (UT1), one is an atomic/solar hybrid (UTC) and four are 
-dynamical times (TT, TCG, TCB, TDB). Other time scales of interest may also be the 
-ones associated to the different positioning systems. In particular: **GPS** (Global 
-Positioning System), **GLONASS** (Global Navigation Satellite System) and **GALILEO** 
-(Global Navigation Satellite System) times could be defined as a constant offset with
-respect to TAI.
+# Create an Epoch from a DateTime object and a timescale
+dt = DateTime(2001, 6, 15, 0, 0, 0, 0.0)
+e = Epoch(dt, TT)
+```
 
-## Time in `JSMD`
+Efficiently transform epochs between various timescales:
+```julia 
+# Convert an Epoch from TAI to TDB 
+tai = Epoch("2022-10-02T12:04:23.043 TAI")
+tdb = convert(TDB, tai)
 
-Within `Tempo`, the way in which time is represented in `Tempo` is through the use of 
-[`Epoch`](@ref)s. `Epoch`s are an efficient, differentiable and precise way to represent 
-astronomical time. To parse an epoch object, two parameters shall be assigned:
+# Convert an Epoch from TAI to UTC automatically handling leapseconds 
+utc = convert(UTC, tai)
+```
 
-- **Timescale**: This parameter determines the timescale that the epoch is based on. 
-    For example, it can be set to UTC, TAI, TDB, or TCB. This allows the user to convert 
-    the epoch between different timescales if necessary.
+## Tempo.jl vs AstroTime.jl 
+Tempo.jl and [AstroTime.jl](https://github.com/JuliaAstro/AstroTime.jl) are very similar libraries that allow transformations between various astronomical time representations. The major differences are:
 
-- **Origin**: This parameter determines the origin of the epoch, which is the point in time 
-    from which the epoch is measured. This can be in the form of a Julian date, a
-    Modified Julian date or any user-defined origin. 
-    The origin can also be set to a specific event, such as J2000.0 or B1950.0.
+- AstroTime.jl supports accurate Epoch transformations by leveraging high 
+    precision arithmetics.
+- Tempo.jl is more efficient when multiple timescales conversions must be 
+    performed to convert a given Epoch (e.g., it does not allocate memory).
 
-By assigning these two parameters, [`Epoch`](@ref)s can be used to represent time in a precise 
-manner, which is crucial for accurate timekeeping and coordination of events in a universe model.
diff --git a/docs/src/lapi.md b/docs/src/lapi.md
@@ -0,0 +1,88 @@
+# [Low-level API](@id tempo_lapi)
+
+These functions are not meant to be used outside of the package. They are documented only to aid future developments of the package.
+
+## Epochs
+```@docs 
+Tempo.AbstractEpochOrigin 
+Tempo.JulianDate 
+Tempo.JulianDate2000
+Tempo.ModifiedJulianDate
+Tempo.ModifiedJulianDate2000
+Tempo.EpochConversionError
+Tempo.parse_iso
+```
+
+## Timescale Offsets 
+```@docs
+Tempo.offset
+Tempo.offset_gps2tai
+
+Tempo.offset_tai2gps
+Tempo.offset_tai2tt
+Tempo.offset_tai2utc
+
+Tempo.offset_tcb2tdb
+Tempo.offset_tcg2tt
+
+Tempo.offset_tdb2tt
+Tempo.offset_tdb2tcb
+
+Tempo.offset_tt2tai
+Tempo.offset_tt2tcg
+Tempo.offset_tt2tdb
+Tempo.offset_tt2tdbh
+
+Tempo.offset_utc2tai
+```
+
+## Timescale Types 
+```@docs 
+Tempo.TimeScaleNode
+Tempo.AbstractTimeScale
+Tempo.GlobalPositioningSystemTime
+Tempo.BarycentricDynamicalTime
+Tempo.HighPrecisionBarycentricDynamicalTime
+Tempo.BarycentricCoordinateTime
+Tempo.TerrestrialTime
+Tempo.InternationalAtomicTime
+Tempo.UniversalTime
+Tempo.CoordinatedUniversalTime
+Tempo.GeocentricCoordinateTime
+```
+
+## Conversions 
+```@docs 
+Base.convert
+
+Tempo.cal2jd
+Tempo.calhms2jd
+Tempo.fd2hms
+Tempo.fd2hmsf
+Tempo.hms2fd
+Tempo.jd2cal
+Tempo.jd2calhms
+
+Tempo.tai2utc
+Tempo.utc2tai
+```
+
+## Leapseconds
+```@docs 
+Tempo.Leapseconds
+Tempo.LEAPSECONDS
+Tempo.get_leapseconds
+Tempo.leapseconds
+```
+
+## Miscellaneous 
+```@docs 
+Tempo.find_year
+Tempo.find_month
+Tempo.find_day
+Tempo.fraction_of_day
+Tempo.fraction_of_second
+Tempo.isleapyear
+Tempo.lastj2000dayofyear
+Tempo.second_in_day
+```