Merge pull request #86 from JuliaAstro/patch-tests-docs

Documentation and test updates and fixes

Project.toml

@@ -16,6 +16,8 @@ julia = "1"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Measurements = "eff96d63-e80a-5855-80a2-b1b0885c5ab7"
 
 [targets]
 test = ["Test"]

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Measurements = "eff96d63-e80a-5855-80a2-b1b0885c5ab7"
 
 [compat]
 Documenter = "0.26, 0.27, 1"

docs/make.jl

@@ -1,10 +1,18 @@
 using Documenter, AstroLib
 
 include("pages.jl")
+
+DocMeta.setdocmeta!(AstroLib, :DocTestSetup, :(using AstroLib), recursive=true)
+
 makedocs(
     modules = [AstroLib],
     sitename = "AstroLib",
-    pages=pages
+    format = Documenter.HTML(
+        size_threshold = 400 * 1024, # 400 KiB because API reference page is big
+        size_threshold_warn = 200 * 1024,
+        #assets = [],
+    ),
+    pages = pages,
 )
 
 deploydocs(

docs/pages.jl

@@ -1,4 +1,4 @@
-pages    = [
-        "Introduction"   => "index.md",
-        "Reference"      => "ref.md",
-    ]
+pages = [
+    "Introduction"  => "index.md",
+    "Reference"     => "ref.md",
+]

docs/src/assets/draw-logo.jl

@@ -25,7 +25,7 @@ function ellipse2c(focus1::Point, focus2::Point, k; stepvalue=pi/100)
 end
 
 """
-Draw a logo with ellipse and colored circles 
+Draw a logo with ellipse and colored circles
 """
 function draw_logo(fname)
     Drawing(500, 500, fname)

docs/src/index.md

@@ -8,9 +8,10 @@ An extensive error testing suite ensures old fixed bugs will not be brought back
 
 ## Installation
 
-AstroLib is available for Julia 1.0 and later versions, and can be installed with [Julia](https://github.com/julialang/julia.jl)'s built-in package manager. In a Julia session run the command
+AstroLib is available for Julia 1.0 and later versions, and can be installed with [Julia](https://github.com/julialang/julia.jl)'s built-in package manager. In a Julia session run the commands
 
-```julia
+```julia-repl
+julia> import Pkg
 julia> Pkg.update()
 julia> Pkg.add("AstroLib")
 ```
@@ -19,7 +20,7 @@ Older versions are also available for Julia 0.4-0.6.
 
 Note that, in order to work, a few functions require external files, which are automatically downloaded when building the package. Should these files be missing for some reason, you will be able to load the package but some functions may not work properly. You can manually build the package with
 
-```julia
+```julia-repl
 julia> Pkg.build("AstroLib")
 ```
 
@@ -33,11 +34,11 @@ using AstroLib
 
 Many functions in `AstroLib.jl` are compatible with [Measurements.jl](https://github.com/giordano/Measurements.jl) package, which allows you to define quantities with uncertainty and propagate the error when performing calculations according to [propagation of uncertainty rules](https://en.wikipedia.org/wiki/Propagation_of_uncertainty). For example:
 
-```julia
+```jldoctest
 julia> using AstroLib, Measurements
 
 julia> mag2flux(12.54 ± 0.03)
-3.499451670283562e-14 ± 9.669342299577655e-16
+3.499e-14 ± 9.7e-16
 ```
 
 ## How Can I Help?
@@ -56,19 +57,19 @@ This project is a work-in-progress, only few procedures have been translated so
 
 Every function provided has detailed documentation that can be [accessed](http://docs.julialang.org/en/stable/manual/documentation/#accessing-documentation) at Julia REPL with
 
-```julia
+```julia-repl
 julia> ?FunctionName
 ```
 
 or with
 
-```julia
+```julia-repl
 julia> @doc FunctionName
 ```
 
 ## Related Projects
 
-This is not the only effort to bundle astronomical functions written in Julia language. Other packages useful for more specific purposes are available at [JuliaAstro](https://juliaastro.github.io/). A list of other packages is available [here](https://github.com/svaksha/Julia.jl/blob/master/Astronomy.md).
+This is not the only effort to bundle astronomical functions written in Julia language. Other packages useful for more specific purposes are available at [JuliaAstro](https://juliaastro.github.io/).
 
 Because of this, some of IDL AstroLib’s utilities are not provided in `AstroLib.jl` as they are already present in other Julia packages. Here is a list of such utilities:
 

docs/src/ref.md

@@ -1,10 +1,13 @@
+```@meta
+DocTestSetup = :(using AstroLib)
+```
 # Reference
 
 ## Data types
 
 ### Observatory
 
-`AstroLib.jl` defines a new `Observatory` type. This can be used to define a new object holding information about an observing site. It is a [composite type] whose fields are
+`AstroLib.jl` defines a new `Observatory` type. This can be used to define a new object holding information about an observing site. It is a [composite type](https://docs.julialang.org/en/v1/manual/types/#Composite-Types) whose fields are
 
 -   `name` (`String` type): the name of the site
 -   `latitude` (`Float64` type): North-ward latitude of the site in degrees
@@ -22,7 +25,7 @@ Observatory(name, lat, long, alt, tz)
 
 A predefined list of some observing sites is provided with `AstroLib.observatories` constant. It is a dictionary whose keys are the abbreviated names of the observatories. For example, you can access information of the European Southern Observatory with
 
-```julia
+```jldoctest
 julia> obs = AstroLib.observatories["eso"]
 Observatory: European Southern Observatory
 latitude:    -29.256666666666668°N
@@ -66,16 +69,20 @@ Planet(name, radius, eqradius, polradius, mass, ecc, axis, period)
 
 The list of Solar System planets, from Mercury to Pluto, is available with `AstroLib.planets` dictionary. The keys of this dictionary are the lowercase names of the planets. For example:
 
-```julia
+```jldoctest
 julia> AstroLib.planets["mercury"]
-Planet:            Mercury
-mean radius:       2.4397e6 m
-equatorial radius: 2.4397e6 m
-polar radius:      2.4397e6 m
-mass:              3.3011e23 kg
-eccentricity:      0.20563069
-semi-major axis:   5.790905e10 m
-period:            5.790905e10 s
+Planet:                      Mercury
+mean radius:                 2.4397e6 m
+equatorial radius:           2.4397e6 m
+polar radius:                2.4397e6 m
+mass:                        3.3011e23 kg
+eccentricity:                0.20563593
+semi-major axis:             5.790922654152439e10 m
+period:                      7.60053024e6 s
+inclination:                 7.00497902 °
+longitude of ascending node: 48.33076593 °
+longitude of perihelion:     77.45779628 °
+mean longitude:              252.2503235 °
 
 julia> AstroLib.planets["mars"].eqradius
 3.3962e6
@@ -88,94 +95,94 @@ julia> AstroLib.planets["saturn"].mass
 
 ### Coordinates and positions
 
-[`adstring()`](@ref),
-[`aitoff()`](@ref),
-[`altaz2hadec()`](@ref),
-[`baryvel()`](@ref),
-[`bprecess()`](@ref),
-[`co_aberration()`](@ref),
-[`co_nutate()`](@ref),
-[`co_refract()`](@ref),
-[`eci2geo()`](@ref),
-[`eq2hor()`](@ref),
-[`eqpole()`](@ref),
-[`euler()`](@ref),
-[`gcirc()`](@ref),
-[`geo2eci()`](@ref),
-[`geo2geodetic()`](@ref),
-[`geo2mag()`](@ref),
-[`geodetic2geo()`](@ref),
-[`hadec2altaz()`](@ref),
-[`helio_rv()`](@ref),
-[`helio()`](@ref),
-[`hor2eq()`](@ref),
-[`jprecess()`](@ref),
-[`mag2geo()`](@ref),
-[`mean_obliquity()`](@ref),
-[`planet_coords()`](@ref),
-[`polrec()`](@ref),
-[`posang()`](@ref),
-[`precess()`](@ref),
-[`precess_cd()`](@ref),
-[`precess_xyz()`](@ref),
-[`premat()`](@ref),
-[`radec()`](@ref),
-[`recpol()`](@ref),
-[`true_obliquity()`](@ref),
-[`zenpos()`](@ref)
+- [`adstring()`](@ref)
+- [`aitoff()`](@ref)
+- [`altaz2hadec()`](@ref)
+- [`baryvel()`](@ref)
+- [`bprecess()`](@ref)
+- [`co_aberration()`](@ref)
+- [`co_nutate()`](@ref)
+- [`co_refract()`](@ref)
+- [`eci2geo()`](@ref)
+- [`eq2hor()`](@ref)
+- [`eqpole()`](@ref)
+- [`euler()`](@ref)
+- [`gcirc()`](@ref)
+- [`geo2eci()`](@ref)
+- [`geo2geodetic()`](@ref)
+- [`geo2mag()`](@ref)
+- [`geodetic2geo()`](@ref)
+- [`hadec2altaz()`](@ref)
+- [`helio_rv()`](@ref)
+- [`helio()`](@ref)
+- [`hor2eq()`](@ref)
+- [`jprecess()`](@ref)
+- [`mag2geo()`](@ref)
+- [`mean_obliquity()`](@ref)
+- [`planet_coords()`](@ref)
+- [`polrec()`](@ref)
+- [`posang()`](@ref)
+- [`precess()`](@ref)
+- [`precess_cd()`](@ref)
+- [`precess_xyz()`](@ref)
+- [`premat()`](@ref)
+- [`radec()`](@ref)
+- [`recpol()`](@ref)
+- [`true_obliquity()`](@ref)
+- [`zenpos()`](@ref)
 
 ### Time and date
 
-[`ct2lst()`](@ref),
-[`daycnv()`](@ref),
-[`get_date()`](@ref),
-[`get_juldate()`](@ref),
-[`helio_jd()`](@ref),
-[`jdcnv()`](@ref),
-[`juldate()`](@ref),
-[`month_cnv()`](@ref),
-[`nutate()`](@ref),
-[`ydn2md()`](@ref),
-[`ymd2dn()`](@ref)
+- [`ct2lst()`](@ref)
+- [`daycnv()`](@ref)
+- [`get_date()`](@ref)
+- [`get_juldate()`](@ref)
+- [`helio_jd()`](@ref)
+- [`jdcnv()`](@ref)
+- [`juldate()`](@ref)
+- [`month_cnv()`](@ref)
+- [`nutate()`](@ref)
+- [`ydn2md()`](@ref)
+- [`ymd2dn()`](@ref)
 
 ### Moon and sun
 
-[`moonpos()`](@ref),
-[`mphase()`](@ref),
-[`sunpos()`](@ref),
-[`xyz()`](@ref)
+- [`moonpos()`](@ref)
+- [`mphase()`](@ref)
+- [`sunpos()`](@ref)
+- [`xyz()`](@ref)
 
 ### Utilities
 
-[`airtovac()`](@ref),
-[`calz_unred()`](@ref),
-[`deredd()`](@ref),
-[`flux2mag()`](@ref),
-[`gal_uvw()`](@ref),
-[`imf()`](@ref),
-[`ismeuv()`](@ref),
-[`kepler_solver()`](@ref),
-[`lsf_rotate()`](@ref),
-[`mag2flux()`](@ref),
-[`paczynski()`](@ref),
-[`planck_freq()`](@ref),
-[`planck_wave()`](@ref),
-[`rad2sec()`](@ref),
-[`rhotheta()`](@ref),
-[`sec2rad()`](@ref),
-[`sixty()`](@ref),
-[`sphdist()`](@ref),
-[`ten()`](@ref),
-[`tic_one()`](@ref),
-[`ticpos()`](@ref),
-[`tics()`](@ref),
-[`trueanom()`](@ref),
-[`uvbybeta()`](@ref),
-[`vactoair()`](@ref)
+- [`airtovac()`](@ref)
+- [`calz_unred()`](@ref)
+- [`deredd()`](@ref)
+- [`flux2mag()`](@ref)
+- [`gal_uvw()`](@ref)
+- [`imf()`](@ref)
+- [`ismeuv()`](@ref)
+- [`kepler_solver()`](@ref)
+- [`lsf_rotate()`](@ref)
+- [`mag2flux()`](@ref)
+- [`paczynski()`](@ref)
+- [`planck_freq()`](@ref)
+- [`planck_wave()`](@ref)
+- [`rad2sec()`](@ref)
+- [`rhotheta()`](@ref)
+- [`sec2rad()`](@ref)
+- [`sixty()`](@ref)
+- [`sphdist()`](@ref)
+- [`ten()`](@ref)
+- [`tic_one()`](@ref)
+- [`ticpos()`](@ref)
+- [`tics()`](@ref)
+- [`trueanom()`](@ref)
+- [`uvbybeta()`](@ref)
+- [`vactoair()`](@ref)
 
 ### Miscellaneous (non-astronomy) functions
 
-[`ordinal()`](@ref)
+- [`ordinal()`](@ref)
 
 ## Types and functions organized alphabetically
 

src/adstring.jl

@@ -77,7 +77,8 @@ julia> adstring.([30.4, -15.63], [-1.23, 48.41], precision=1)
  " 22 57 28.80  +48 24 36.0"
 ```
 """
-function adstring(ra::T, dec::T; precision::Int=0,
+function adstring(ra::T, dec::T;
+                  precision::Int=0,
                   truncate::Bool=false) where {T<:AbstractFloat}
     # XXX: IDL implementation takes also real values for "precision" and
     # truncates it.  I think it's better to enforce an integer type and cure

src/airtovac.jl

@@ -27,8 +27,8 @@ Converts air wavelengths to vacuum wavelengths.
 ### Explanation ###
 
 Wavelengths are corrected for the index of refraction of air under standard conditions.
-Wavelength values below \$2000 Å\$ will *not* be altered, take care within \$[1 Å, 2000
-Å]\$.  Uses relation of Ciddor (1996).
+Wavelength values below ``2000 Å`` will *not* be altered, take care within
+``[1 Å, 2000 Å]``.  Uses relation of Ciddor (1996).
 
 ### Arguments ###