Update docstrings to work better with Documenter.jl (#84)

* Fix star name by moving HD to newline

Markdown was reading HD<newline>119288., where 119288. was read as the
start of an ordered list.

* Fix lists and unicode in docstrings

Adjust markdown in docstrings so that lists are grouped properly,
the unicode characters render properly for REPL help, and
for sunpos(), use the actual default value for radians.

* Add newline to src/sunpos.jl

Co-authored-by: Mosè Giordano <giordano@users.noreply.github.com>

---------

Co-authored-by: Mosè Giordano <giordano@users.noreply.github.com>

src/adstring.jl

@@ -72,7 +72,7 @@ julia> adstring(30.4, -1.23, truncate=true)
 " 02 01 35.9  -01 13 48"
 
 julia> adstring.([30.4, -15.63], [-1.23, 48.41], precision=1)
-2-element Array{String,1}:
+2-element Vector{String}:
  " 02 01 36.00  -01 13 48.0"
  " 22 57 28.80  +48 24 36.0"
 ```

src/bprecess.jl

@@ -184,8 +184,8 @@ http://adsabs.harvard.edu/abs/1983A%26A...128..263A.
 
 ### Example ###
 
-The SAO2000 catalogue gives the J2000 position and proper motion for the star HD
-119288.  Find the B1950 position.
+The SAO2000 catalogue gives the J2000 position and proper motion for the star
+HD 119288.  Find the B1950 position.
 
 * RA(2000) = 13h 42m 12.740s
 * Dec(2000) = 8d 23' 17.69''
@@ -217,4 +217,4 @@ and equinox of J2000.0" -- from the Explanatory Supplement (1992), p. 180
 
 Code of this function is based on IDL Astronomy User's Library.
 """
-bprecess
+function bprecess end

src/co_aberration.jl

@@ -63,8 +63,9 @@ julia> co_aberration(jd,ten(2,46,11.331)*15,ten(49,20,54.54))
 (30.04404628365077, 6.699400463119431)
 ```
 
-d_ra = 30.04404628365103'' (≈ 2.003s)
-d_dec = 6.699400463118504''
+d\\_ra = 30.04404628365103'' (≈ 2.003s)
+
+d\\_dec = 6.699400463118504''
 
 ### Notes ###
 

src/co_refract.jl

@@ -150,7 +150,7 @@ Code of this function is based on IDL Astronomy User's Library.
 function co_refract_forward(alt::Real, pre::Real, temp::Real)
 
     if alt < 15
-        ref =3.569*@evalpoly(alt, 0.1594, 0.0196, 0.00002)/@evalpoly(alt, 1, 0.505, 0.0845)
+        ref = 3.569*@evalpoly(alt, 0.1594, 0.0196, 0.00002)/@evalpoly(alt, 1, 0.505, 0.0845)
     else
         ref = 0.0166667 / tand((alt + 7.31 / (alt + 4.4)))
     end

src/ct2lst.jl

@@ -22,9 +22,9 @@ Convert from Local Civil Time to Local Mean Sidereal Time.
 The function can be called in two different ways.  The only argument common to
 both methods is `longitude`:
 
-* `longitude`: the longitude in degrees (east of Greenwich) of the place for which the local
-  sidereal time is desired.  The Greenwich mean sidereal time (GMST) can be found by setting
-  longitude = `0`.
+* `longitude`: the longitude in degrees (east of Greenwich) of the place for which
+  the local sidereal time is desired.  The Greenwich mean sidereal time (GMST) can
+  be found by setting longitude = `0`.
 
 The civil date to be converted to mean sidereal time can be specified either by
 providing the Julian days:
@@ -62,7 +62,7 @@ julia> lst = ct2lst(-76.72, -4, DateTime(2008, 7, 30, 15, 53))
 11.356505172312609
 
 julia> sixty(lst)
-3-element StaticArrays.SArray{Tuple{3},Float64,1,3} with indices SOneTo(3):
+3-element StaticArraysCore.SVector{3, Float64} with indices SOneTo(3):
  11.0
  21.0
  23.418620325392112
@@ -76,17 +76,18 @@ Julian days.
 ```jldoctest
 julia> using AstroLib, Dates
 
-julia> longitude=ten(8, 43); # Convert longitude to decimals.
+julia> longitude = ten(8, 43); # Convert longitude to decimals.
+
+julia> # Get number of Julian days. Remember to subtract the time zone in
+       # order to convert local time to UTC.
 
 julia> jd = jdcnv(DateTime(2015, 11, 24, 13, 21) - Dates.Hour(1));
-# Get number of Julian days. Remember to subtract the time zone in
-# order to convert local time to UTC.
 
 julia> lst = ct2lst(longitude, jd) # Calculate Greenwich Mean Sidereal Time.
 17.140685171005316
 
 julia> sixty(lst)
-3-element StaticArrays.SArray{Tuple{3},Float64,1,3} with indices SOneTo(3):
+3-element StaticArraysCore.SVector{3, Float64} with indices SOneTo(3):
  17.0
   8.0
  26.466615619137883
@@ -96,6 +97,8 @@ julia> sixty(lst)
 
 Code of this function is based on IDL Astronomy User's Library.
 """
+function ct2lst end
+
 ct2lst(long::Real, jd::Real) = ct2lst(promote(float(long), float(jd))...)
 
 function ct2lst(long::T, tz::T, date::DateTime) where {T<:AbstractFloat}

src/daycnv.jl

@@ -35,4 +35,4 @@ julia> daycnv(2440000)
 
 `jdcnv` is the inverse of this function.
 """
-const daycnv=Dates.julian2datetime
+const daycnv = Dates.julian2datetime

src/eci2geo.jl

@@ -45,9 +45,9 @@ The three coordinates can be passed as a 3-tuple `(x, y, z)`.  In addition, `x`,
 
 The 3-tuple of geographical coordinate (latitude, longitude, altitude).
 
-* latitude: latitude, in degrees.
-* longitude: longitude, in degrees.
-* altitude: altitude, in kilometers.
+* `latitude`: latitude, in degrees.
+* `longitude`: longitude, in degrees.
+* `altitude`: altitude, in kilometers.
 
 If ECI coordinates are given as arrays, a 3-tuple of arrays of the same length
 is returned.
@@ -93,8 +93,7 @@ function eci2geo(x::AbstractArray{X}, y::AbstractArray{<:Real}, z::AbstractArray
     long = similar(x, typex)
     alt  = similar(x, typex)
     for i in eachindex(x)
-        lat[i], long[i], alt[i] =
-            eci2geo(x[i], y[i], z[i], jd[i])
+        lat[i], long[i], alt[i] = eci2geo(x[i], y[i], z[i], jd[i])
     end
     return lat, long, alt
 end

src/euler.jl

@@ -107,7 +107,7 @@ function euler(ai::AbstractVector{R}, bi::AbstractVector{<:Real}, select::Intege
     bi_out = similar(bi, typeai)
     for i in eachindex(ai)
         ai_out[i], bi_out[i] = euler(ai[i], bi[i], select,
-                                        FK4=FK4, radians=radians)
+                                     FK4=FK4, radians=radians)
     end
     return ai_out, bi_out
 end

src/flux2mag.jl

@@ -25,23 +25,25 @@ This is the reverse of `mag2flux`.
 * `flux`: the flux to be converted in magnitude, expressed in
   erg/(s cm² Å).
 * `zero_point`: the zero point level of the magnitude.  If not
- supplied then defaults to 21.1 (Code et al 1976).  Ignored if the `ABwave`
- keyword is supplied
+  supplied then defaults to 21.1 (Code et al 1976).  Ignored if the `ABwave`
+  keyword is supplied
 * `ABwave` (optional numeric keyword): wavelength in Angstroms.
- If supplied, then returns Oke AB magnitudes (Oke & Gunn 1983, ApJ, 266, 713;
- http://adsabs.harvard.edu/abs/1983ApJ...266..713O).
+  If supplied, then returns Oke AB magnitudes (Oke & Gunn 1983, ApJ, 266, 713;
+  http://adsabs.harvard.edu/abs/1983ApJ...266..713O).
 
 ### Output ###
 
 The magnitude.
 
 If the `ABwave` keyword is set then magnitude is given by the expression
-
-\$\$\\text{ABmag} = -2.5\\log_{10}(f) - 5\\log_{10}(\\text{ABwave}) - 2.406\$\$
+```math
+\\text{ABmag} = -2.5\\log_{10}(f) - 5\\log_{10}(\\text{ABwave}) - 2.406
+```
 
 Otherwise, magnitude is given by the expression
-
-\$\$\\text{mag} = -2.5\\log_{10}(\\text{flux}) - \\text{zero point}\$\$
+```math
+\\text{mag} = -2.5\\log_{10}(\\text{flux}) - \\text{zero point}
+```
 
 ### Example ###
 

src/gal_uvw.jl

@@ -47,26 +47,26 @@ coordinates, (2) proper motion, (3) parallax, and (4) radial velocity.
 User must supply a position, proper motion, radial velocity and parallax.
 Either scalars or arrays all of the same length can be supplied.
 
-(1) Position:
+1. Position:
 
-* `ra`: right ascension, in degrees
-* `dec`: declination, in degrees
+   * `ra`: right ascension, in degrees
+   * `dec`: declination, in degrees
 
-(2) Proper Motion
+2. Proper Motion
 
-* `pmra`: proper motion in right ascension in arc units (typically
-  milli-arcseconds/yr).  If given \$\\mu_\\alpha\$ -- proper motion in seconds of
-  time/year -- then this is equal to \$15 \\mu_\\alpha \\cos(\\text{dec})\$.
-* `pmdec`: proper motion in declination (typically mas/yr).
+   * `pmra`: proper motion in right ascension in arc units (typically
+     milli-arcseconds/yr).  If given \$\\mu_\\alpha\$ -- proper motion in seconds of
+     time/year -- then this is equal to \$15 \\mu_\\alpha \\cos(\\text{dec})\$.
+   * `pmdec`: proper motion in declination (typically mas/yr).
 
-(3) Radial Velocity
+3. Radial Velocity
 
-* `vrad`: velocity in km/s
+   * `vrad`: velocity in km/s
 
-(4) Parallax
+4. Parallax
 
-* `plx`: parallax with same distance units as proper motion measurements
-  typically milliarcseconds (mas)
+   * `plx`: parallax with same distance units as proper motion measurements
+     typically milliarcseconds (mas)
 
 If you know the distance in parsecs, then set `plx` to \$1000/\\text{distance}\$,
 if proper motion measurements are given in milli-arcseconds/yr.
@@ -105,7 +105,7 @@ Hipparcos catalog, and correct to the LSR.
 ```jldoctest
 julia> using AstroLib
 
-julia> ra=ten(1,9,42.3)*15.; dec = ten(61,32,49.5);
+julia> ra = ten(1,9,42.3)*15.; dec = ten(61,32,49.5);
 
 julia> pmra = 627.89;  pmdec = 77.84; # mas/yr
 

src/gcirc.jl

@@ -87,7 +87,7 @@ julia> gcirc(0, 120, -43, 175, +22)
 ### Notes ###
 
 * The function `sphdist` provides an alternate method of computing a spherical
- distance.
+  distance.
 * The Haversine formula can give rounding errors for antipodal points.
 
 Code of this function is based on IDL Astronomy User's Library.

src/geo2eci.jl

@@ -87,8 +87,7 @@ function geo2eci(lat::AbstractArray{LA}, long::AbstractArray{<:Real},
     y = similar(lat, typela)
     z = similar(lat, typela)
     for i in eachindex(lat)
-        x[i], y[i], z[i] =
-            geo2eci(lat[i], long[i], alt[i], jd[i])
+        x[i], y[i], z[i] = geo2eci(lat[i], long[i], alt[i], jd[i])
     end
     return x, y, z
 end

src/geo2geodetic.jl

@@ -141,7 +141,7 @@ planetodetic) to geographic coordinates, can be used to estimate the accuracy of
 julia> using AstroLib
 
 julia> collect(geodetic2geo(geo2geodetic(67.2, 13.4, 1.2))) - [67.2, 13.4, 1.2]
-3-element Array{Float64,1}:
+3-element Vector{Float64}:
  -3.5672513831741526e-9
   0.0
   9.484211194177306e-10

src/geo2mag.jl

@@ -70,7 +70,7 @@ geomagnetic coordinates in 2016:
 julia> using AstroLib
 
 julia> geo2mag(ten(35,0,42), ten(135,46,6), 2016)
-(36.86579228937769, -60.184060536651614)
+(36.86579228937769, -60.1840605366516)
 ```
 
 ### Notes ###

src/get_date.jl

@@ -55,11 +55,11 @@ julia> get_date(DateTime(21937, 05, 30, 09, 59, 00), timetag=true)
 ### Notes ###
 
 1. A discussion of the DATExxx syntax in FITS headers can be found in
- http://www.cv.nrao.edu/fits/documents/standards/year2000.txt
+   http://www.cv.nrao.edu/fits/documents/standards/year2000.txt
 
 2. Those who wish to use need further flexibility in their date formats (e.g. to
- use TAI time) should look at Bill Thompson's time routines in
- http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/time
+   use TAI time) should look at Bill Thompson's time routines in
+   http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/time
 """
 function get_date(dt::DateTime, old::Bool, timetag::Bool)
     # Based on `Base.string' definition in base/dates/io.jl.

src/helio.jl

@@ -13,7 +13,7 @@ const dpd = @SMatrix [ 0.00000037  0.00001906 -0.00594749 -0.12534081  0.1604768
                       -0.00031596  0.00005170  0.00004818 -0.01183482 -0.04062942    145.20780515]
 
 const record = Dict(1=>"mercury", 2=>"venus", 3=>"earth", 4=>"mars", 5=>"jupiter",
-                  6=>"saturn", 7=>"uranus", 8=>"neptune", 9=>"pluto")
+                    6=>"saturn", 7=>"uranus", 8=>"neptune", 9=>"pluto")
 
 function _helio(jd::T, num::Integer, radians::Bool) where {T<:AbstractFloat}
 
@@ -63,8 +63,8 @@ for Saturn.
 * `jd`: julian date, scalar or vector
 * `num`: integer denoting planet number, scalar or vector
   1 = Mercury, 2 = Venus, ... 9 = Pluto
-* `radians`(optional): if this keyword is set to
-  `true`, than the longitude and latitude output are in radians rather than degrees.
+* `radians`(optional): if this keyword is set to `true`, then
+  the longitude and latitude output are in radians rather than degrees.
 
 ### Output ###
 
@@ -74,32 +74,32 @@ for Saturn.
 
 ### Example ###
 
-(1) Find heliocentric position of Venus on August 23, 2000
+- Find heliocentric position of Venus on August 23, 2000
 
-```jldoctest
-julia> using AstroLib
+  ```jldoctest
+  julia> using AstroLib
 
-julia> helio(jdcnv(2000,08,23,0), 2)
-(0.7213758288364316, 198.39093251916148, 2.887355631705488)
-```
+  julia> helio(jdcnv(2000,08,23,0), 2)
+  (0.7213758288364316, 198.39093251916148, 2.887355631705488)
+  ```
 
-(2) Find the current heliocentric positions of all the planets
+- Find the current heliocentric positions of all the planets
 
-```jldoctest
-julia> using AstroLib
+  ```jldoctest
+  julia> using AstroLib
 
-julia> helio.([jdcnv(1900)], 1:9)
-9-element Array{Tuple{Float64,Float64,Float64},1}:
- (0.4207394142180803, 202.60972662618906, 3.0503005607270532)
- (0.7274605731764012, 344.5381482401048, -3.3924346961624785)
- (0.9832446886519147, 101.54969268801035, 0.012669354526696368)
- (1.4212659241051142, 287.8531100442217, -1.5754626002228043)
- (5.386813769590955, 235.91306092135062, 0.9131692817310215)
- (10.054339927304339, 268.04069870870387, 1.0851704598594278)
- (18.984683376211326, 250.0555468087738, 0.05297087029604253)
- (29.87722677219009, 87.07244903504716, -1.245060583142733)
- (46.9647515992327, 75.94692594417324, -9.576681044165511)
-```
+  julia> helio.([jdcnv(1900)], 1:9)
+  9-element Vector{Tuple{Float64, Float64, Float64}}:
+   (0.4207394142180803, 202.60972662618906, 3.0503005607270532)
+   (0.7274605731764012, 344.5381482401048, -3.3924346961624785)
+   (0.9832446886519147, 101.54969268801035, 0.012669354526696368)
+   (1.4212659241051142, 287.8531100442217, -1.5754626002228043)
+   (5.386813769590955, 235.91306092135062, 0.9131692817310215)
+   (10.054339927304339, 268.04069870870387, 1.0851704598594278)
+   (18.984683376211326, 250.0555468087738, 0.05297087029604253)
+   (29.87722677219009, 87.07244903504716, -1.245060583142733)
+   (46.9647515992327, 75.94692594417324, -9.576681044165511)
+  ```
 ### Notes ###
 
 This program is based on the two-body model and thus neglects
@@ -123,8 +123,7 @@ function helio(jd::AbstractVector{P}, num::AbstractVector{<:Real},
     hlong_out = similar(jd,  typejd)
     hlat_out = similar(jd,  typejd)
     for i in eachindex(jd)
-        hrad_out[i], hlong_out[i], hlat_out[i] =
-        helio(jd[i], num[i], radians)
+        hrad_out[i], hlong_out[i], hlat_out[i] = helio(jd[i], num[i], radians)
     end
     return hrad_out, hlong_out, hlat_out
 end