Merge pull request #342 from ajwheeler/update_documenter

update Documenter.jl to v1

docs/Project.toml

@@ -2,4 +2,4 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 
 [compat]
-Documenter = "0.27"
+Documenter = "1"

docs/make.jl

@@ -1,36 +1,24 @@
-push!(LOAD_PATH, "../src/")
+#push!(LOAD_PATH, "../src/")
 
 using Documenter, Korg
 
-makedocs(; sitename="Korg",
+makedocs(;
          modules=[Korg],
+         repo=Documenter.Remotes.GitHub("ajwheeler", "Korg.jl"),
+         sitename="Korg",
          pages=["Quickstart" => "index.md"
                 "Install" => "install.md"
                 "Tutorials" => "tutorials.md"
                 "High-level API" => "API.md"
                 "FAQ" => "FAQ.md"
                 "Changelog" => "changelog.md"
                 "Developer Documentation" => "devdocs.md"],
-         checkdocs=:all, # make sure all docstrings are in the documentation
-         #linkcheck = true, # check if any external links are broken (too many ADS links time out.)
-         #linkcheck_timeout = 30, # default (10s) is too short for slow academic sites
-         linkcheck_ignore=[],
-         strict=[:doctest,
-             :linkcheck,
-             :parse_error,
-             :example_block,
-             # This will error on duplicate functions docs, which we currently have by design
-             #:autodocs_block, 
-             :cross_references,
-             :docs_block,
-             :eval_block,
-             :example_block,
-             :footnote,
-             :meta_block,
-             :missing_docs,
-             :setup_block],
-         authors="Adam Wheeler and Matthew Abruzzo",
-         format=Documenter.HTML(; assets=["assets/favicon.ico"]))
-
-deploydocs(; repo="github.com/ajwheeler/Korg.jl.git",
-           devbranch="main")
+         linkcheck=true, # check if any external links are broken 
+         linkcheck_timeout=30, # default (10s) is too short for slow academic sites
+         # dodgy academic links sometimes timeout
+         linkcheck_ignore=["https://marcs.astro.uu.se/"],
+         authors="Adam Wheeler, Matthew Abruzzo, Andrew Casey, and collaborators",
+         format=Documenter.HTML(; assets=["assets/favicon.ico"], size_threshold=500000),)
+checkdocs = :all, # make sure all docstrings are in the documentation
+            deploydocs(; repo="github.com/ajwheeler/Korg.jl.git",
+                       devbranch="main")

docs/src/API.md

@@ -43,55 +43,6 @@ Korg.air_to_vacuum
 Korg.vacuum_to_air
 ```
 
-## Line absorption 
-These functions can be used to directly compute line opacities. 
-
-```@docs
-Korg.line_absorption!
-Korg.line_profile
-Korg.hydrogen_line_absorption!
-Korg.voigt_hjerting
-```
-
-## Continuum absorption
-These function can be used to directly compute continuum absorption coefficients.
-
-##### Continuum Absorption Kwargs
-
-All bound-free and free-free absorption functions (other than `absorption_coef_bf_TOPBase`) support
-the following keyword arguments:
-
-- `error_oobounds::Bool`: specifies the function's behavior when it encounters invalid `ν` or `T`
-  values. When `false` (the default), the function assumes that the absorption coefficient for
-  these invalid `ν` or `T` values is `0.0`. Otherwise, a `DomainError` is thrown when invalid `ν`
-  or `T` values are encountered.
-- `out_α::Union{Nothing,AbstractVector}`: When this is `nothing` (the default case), the function
-  will simply allocate a new vector to store the output continuum absorption coefficients.
-  Alternatively, this can be a vector (with the same length as the function's `ν` argument). In
-  this case, the function will directly add the computed continuum absorption to the elements of
-  this vector, in-place (the vector is also returned by the function).
-
-```@docs
-Korg.total_continuum_absorption
-Korg.ContinuumAbsorption.H_I_bf
-Korg.ContinuumAbsorption.Hminus_bf
-Korg.ContinuumAbsorption.Hminus_ff
-Korg.ContinuumAbsorption.H2plus_bf_and_ff
-Korg.ContinuumAbsorption.Heminus_ff
-Korg.ContinuumAbsorption.electron_scattering
-Korg.ContinuumAbsorption.rayleigh
-Korg.ContinuumAbsorption.positive_ion_ff_absorption!
-```
-
-## Statistical mechanics
-These functions can be used to calculate the number densities of all species in a given atmospheric 
-layer, or other statmech calculations. 
-
-```@docs
-Korg.saha_ion_weights
-Korg.chemical_equilibrium
-```
-
 ## Misc
 
 ```@docs

docs/src/devdocs.md

@@ -18,7 +18,22 @@ If you've never developed a package in Julia, here are some tips.
 - Unless they will never be called elsewhere, provide docstrings describing the inputs, assumptions and outputs of any functions you write.
 
 ## Continuum absorption
-Steps for implementing new continuum sources of absorption:
+
+### Continuum Absorption Kwargs
+All bound-free and free-free absorption functions (other than `absorption_coef_bf_TOPBase`) support
+the following keyword arguments:
+
+- `error_oobounds::Bool`: specifies the function's behavior when it encounters invalid `ν` or `T`
+  values. When `false` (the default), the function assumes that the absorption coefficient for
+  these invalid `ν` or `T` values is `0.0`. Otherwise, a `DomainError` is thrown when invalid `ν`
+  or `T` values are encountered.
+- `out_α::Union{Nothing,AbstractVector}`: When this is `nothing` (the default case), the function
+  will simply allocate a new vector to store the output continuum absorption coefficients.
+  Alternatively, this can be a vector (with the same length as the function's `ν` argument). In
+  this case, the function will directly add the computed continuum absorption to the elements of
+  this vector, in-place (the vector is also returned by the function).
+
+### Steps for implementing new continuum sources of absorption:
 - Define a helper function that computes a single absorption coefficient (in units of cm⁻²). The function should accept `ν` (in Hz) and `T` (in K) as the first and second arguments, respectively. The convention is for it should share a name with the corresponding public function, but have an underscore pre-appended (e.g. we define `_H_I_bf` to help implement `H_I_bf`).
 - The public function is the function constructed and returned by `Korg.ContinuumAbsorption.bounds_checked_absorption` that wraps the above helper function. This wrapper function implements bounds-checking for `ν` and `T` and supports the keyword arguments described in [Continuum Absorption Kwargs](@ref).
 - Add a docstring describing the new function. At the very least, please describe any non-standard arguments and include a reference in the docstring to the source where the function was taken from.
@@ -42,9 +57,6 @@ If you are adding data to Korg, `data/README` provides an overview of the option
 between them.
 
 ## Complete API
-Here are all the documented methods in Korg.
-
 ```@autodocs
-Modules = [Korg, Korg.Fit, Korg.CubicSplines, Korg.ContinuumAbsorption, Korg.ContinuumAbsorption.Stancil1994,
-Korg.ContinuumAbsorption.Peach1970, Korg.RadiativeTransfer]
+Modules = [Korg, Korg.Fit, Korg.CubicSplines, Korg.ContinuumAbsorption, Korg.ContinuumAbsorption.Stancil1994, Korg.ContinuumAbsorption.Peach1970, Korg.RadiativeTransfer]
 ```

docs/src/tutorials.md

@@ -3,5 +3,5 @@ Here are a few tutorials in the form of Jupyter Notebooks to help you get starte
 - [The Basics](https://github.com/ajwheeler/Korg.jl/tree/main/misc/Tutorial%20notebooks/basics) demonstrates how to read linelists, read or interpolate model atmospheres, and synthesize spectra. It also goes into some of the other data returned when you synthesize a spectrum.
 - [Fitting](https://github.com/ajwheeler/Korg.jl/tree/main/misc/Tutorial%20notebooks/fitting) demonstrates the use of [`Korg.Fit.fit_spectrum`](@ref) to fit observational data.
 
-# [Slurm example]
-There is an example script [here](https://github.com/ajwheeler/Korg.jl/tree/main/misc/examples/generate_grid_with_slurm.jl) that shows how you might use Korg to generate many spectra within a Slurm job. Note that this example creates a file for each spectrum, which may not be desireable on your HPC environment.
+# Slurm example
+[There is an example script](https://github.com/ajwheeler/Korg.jl/tree/main/misc/examples/generate_grid_with_slurm.jl) that shows how you might use Korg to generate many spectra within a Slurm job. Note that this example creates a file for each spectrum, which may not be desireable on your HPC environment.

src/line_absorption.jl

@@ -170,8 +170,9 @@ scaled_stark(γstark, T; T₀=10_000) = γstark * (T / T₀)^(1 / 6)
     scaled_vdW(vdW, m, T)
 
 The vdW broadening gamma scaled acording to its temperature dependence, using either simple scaling
-or ABO. See Anstee & O'Mara (1995) or https://www.astro.uu.se/~barklem/howto.html for the definition
-of the ABO γ.
+or ABO. See Anstee & O'Mara (1995) or
+[Paul Barklem's notes](https://github.com/barklem/public-data/tree/master/broadening-howto) for the
+definition of the ABO γ.
 
 `vdW` should be either `γ_vdW` evaluated at 10,000 K, or tuple containing the ABO params `(σ, α)`.
 The species mass, `m`, is ignored in the former case.

src/linelist.jl

@@ -29,8 +29,8 @@ struct Line{F1,F2,F3,F4,F5,F6}
          - `log10(γ_vdW)`, assumed if negative
          - 0, corresponding to no vdW broadening
          - A fudge factor for the Unsoeld approximation, assumed if between 0 and 20
-         - The [ABO parameters](https://www.astro.uu.se/~barklem/howto.html) as packed float 
-           (assumed if >= 20) or a `Tuple`, `(σ, α)`.
+         - The [ABO parameters](https://github.com/barklem/public-data/tree/master/broadening-howto)
+           as packed float (assumed if >= 20) or a `Tuple`, `(σ, α)`.
 
         This behavior is intended to mirror that of Turbospectrum as closely as possible.