Add obs_tbl to README.md and augment docstring (#39)

* Add obs_tbl to README.md and augment docstring

This adds `obs_tbl` to README.md and adds an `# Extended help` section
to its docstring describing all the supported keyword arguments.

* Fix typo

* Bump version to 0.4.5

Project.toml

@@ -2,7 +2,7 @@ name = "HORIZONS"
 uuid = "5a3ac768-beb4-554a-9c98-3342fe3377f5"
 repo = "https://github.com/PerezHz/HORIZONS.jl.git"
 authors = ["Jorge A. Pérez Hernández", "Luis Eduardo Ramírez Montoya"]
-version = "0.4.4"
+version = "0.4.5"
 
 [deps]
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"

README.md

@@ -53,7 +53,8 @@ enabled.
 Jon D. Giorgini for automated generation of small-body binary SPK files and tables.
 These scripts were originally written in `expect`, and can be found at the
 JPL's Solar System Dynamics group ftp server `ftp://ssd.jpl.nasa.gov/pub/ssd/SCRIPTS/`.
-Below, we describe the functions `smb_spk`, `smb_spk_ele` and `vec_tbl`.
+Below, we describe these functions `smb_spk`, `smb_spk_ele`, and `vec_tbl`, as
+well as the *observer table* function `obs_tbl`.
 
 #### `smb_spk`
 
@@ -144,6 +145,58 @@ apophisvt = vec_tbl("Apophis", t_start, t_stop, δt)
 # Do stuff with `apophisvt` inside julia...
 ```
 
+#### `obs_tbl`
+
+`HORIZONS.jl` function `obs_tbl` allows the user to generate observer tables for
+designated objects and save the output into a file:
+
+```julia
+# Date variables for start and stop times
+t_start = DateTime(2020,7,16, 22)
+t_stop = Date(2020,7,16, 24)
+
+# Step size (allowed types: Period, Int, String)
+δt = Minute(1) # 1 minute step size
+
+# Generate observer table for Voyager 1 as seen from the Green Bank Telescope
+# and save output to Voyager1.csv in current directory:
+obs_tbl("Voyager 1", t_start, t_stop, δt; FILENAME = "Voyager1.csv", CENTER = "GBT", CSV_FORMAT = true)
+```
+
+If the output file is not specified, then `obs_tbl` returns the output as a
+`String`, which may be then used for further processing within Julia.
+
+This table summarizes the available keyword argument names, types, default
+values, and a brief description:
+
+| Keyword::Type                 | Default      | Description                  |
+|:------------------------------|:------------:|:-----------------------------|
+| `FILENAME::String`            | ""           | Output filename              |
+| `CENTER::String`              | "Geocentric" | Observing site               |
+| `COORD_TYPE::String`          | "GEODETIC"   | Type of user coordinates     |
+| `SITE_COORD::String`          | "0,0,0"      | User coordinates for CENTER  |
+| `QUANTITIES::String`          | "A"          | list of quantities to return |
+| `REF_SYSTEM::String`          | "ICRF"       | Astrometric reference frame  |
+| `CAL_FORMAT::String`          | "CAL"        | Type of date output          |
+| `CAL_TYPE::String`            | "MIXED"      | Type of calendar             |
+| `ANG_FORMAT::String`          | "HMS"        | RA/dec angle format          |
+| `APPARENT::String`            | "AIRLESS"    | Toggle refractive correction |
+| `TIME_DIGITS::String`         | "MINUTES"    | Output time precision        |
+| `TIME_ZONE::String`           | "+00:00"     | Local time offset from UTC   |
+| `RANGE_UNITS::String `        | "AU"         | Units for range quantities   |
+| `SUPPRESS_RANGE_RATE::Bool`   | false        | Turns off delta-dot and rdot |
+| `ELEV_CUT::Real`              | -90.0        | Elevation cutoff             |
+| `SKIP_DAYLT::Bool`            | false        | Skip when CENTER in daylight |
+| `SOLAR_ELONG::NTuple{2,Real}` | (0,180)      | Solar elongation bounds      |
+| `AIRMASS::Real`               | 38.0         | Airmass cutoff, horizon=~38  |
+| `LHA_CUTOFF::Real`            | 0.0          | Local hour angle cutoff      |
+| `ANG_RATE_CUTOFF::Real`       | 0.0          | Angular rate cutoff          |
+| `EXTRA_PREC::Bool`            | false        | Output extra precision       |
+| `R_T_S_ONLY::Bool`            | false        | Only output rise/transit/set |
+| `CSV_FORMAT::Bool`            | false        | Output in CSV format         |
+| `MAKE_EPHEM::Bool`            | true         | Generate ephemeris           |
+| `OBJ_DATA::Bool`              | true         | Include object summary       |
+
 ### Small-Body DataBase API
 
 `HORIZONS.jl` function `sbdb` fetchs data for a specific small-body in JPL's Small-Body

src/obstbl.jl

@@ -7,7 +7,7 @@ with step `STEP_SIZE`. If `FILENAME` is empty, return the output as a `String`;
 otherwise, save the table to the corresponding file. For more information see
 [1], in particular the **Common Parameters** and **SPK File Parameters**
 sections; for a list of keyword arguments see the **Ephemeris-Specific
-Parameters** section.
+Parameters** section (or the extended help).
 
 !!! reference
     [1] https://ssd-api.jpl.nasa.gov/doc/horizons.html.
@@ -32,6 +32,39 @@ julia> local_file = obs_tbl("Voyager 1", t_start, t_stop, δt;
 julia> isfile(local_file)
 true
 ```
+
+# Extended help
+
+This table summarizes the available keyword argument names, types, default
+values, and a brief description:
+
+| Keyword::Type                 | Default      | Description                  |
+|:------------------------------|:------------:|:-----------------------------|
+| `FILENAME::String`            | ""           | Output filename              |
+| `CENTER::String`              | "Geocentric" | Observing site               |
+| `COORD_TYPE::String`          | "GEODETIC"   | Type of user coordinates     |
+| `SITE_COORD::String`          | "0,0,0"      | User coordinates for CENTER  |
+| `QUANTITIES::String`          | "A"          | list of quantities to return |
+| `REF_SYSTEM::String`          | "ICRF"       | Astrometric reference frame  |
+| `CAL_FORMAT::String`          | "CAL"        | Type of date output          |
+| `CAL_TYPE::String`            | "MIXED"      | Type of calendar             |
+| `ANG_FORMAT::String`          | "HMS"        | RA/dec angle format          |
+| `APPARENT::String`            | "AIRLESS"    | Toggle refractive correction |
+| `TIME_DIGITS::String`         | "MINUTES"    | Output time precision        |
+| `TIME_ZONE::String`           | "+00:00"     | Local time offset from UTC   |
+| `RANGE_UNITS::String `        | "AU"         | Units for range quantities   |
+| `SUPPRESS_RANGE_RATE::Bool`   | false        | Turns off delta-dot and rdot |
+| `ELEV_CUT::Real`              | -90.0        | Elevation cutoff             |
+| `SKIP_DAYLT::Bool`            | false        | Skip when CENTER in daylight |
+| `SOLAR_ELONG::NTuple{2,Real}` | (0,180)      | Solar elongation bounds      |
+| `AIRMASS::Real`               | 38.0         | Airmass cutoff, horizon=~38  |
+| `LHA_CUTOFF::Real`            | 0.0          | Local hour angle cutoff      |
+| `ANG_RATE_CUTOFF::Real`       | 0.0          | Angular rate cutoff          |
+| `EXTRA_PREC::Bool`            | false        | Output extra precision       |
+| `R_T_S_ONLY::Bool`            | false        | Only output rise/transit/set |
+| `CSV_FORMAT::Bool`            | false        | Output in CSV format         |
+| `MAKE_EPHEM::Bool`            | true         | Generate ephemeris           |
+| `OBJ_DATA::Bool`              | true         | Include object summary       |
 """
 function obs_tbl(COMMAND::ObjectName, START_TIME::StartStopTime, STOP_TIME::StartStopTime,
                  STEP_SIZE::StepSize; FILENAME::String = "", CENTER::String = "Geocentric",