From 53ec27baa248588b9589b40a586dfe60122177b8 Mon Sep 17 00:00:00 2001 From: Adam Wheeler Date: Tue, 8 Oct 2024 19:53:28 -0400 Subject: [PATCH 1/3] update documenter --- docs/Project.toml | 2 +- docs/make.jl | 26 +++++++------------------- 2 files changed, 8 insertions(+), 20 deletions(-) diff --git a/docs/Project.toml b/docs/Project.toml index 3a52a5db..1814eb33 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -2,4 +2,4 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" [compat] -Documenter = "0.27" +Documenter = "1" diff --git a/docs/make.jl b/docs/make.jl index 46296856..aaeb47f9 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,9 +1,11 @@ -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" @@ -12,23 +14,9 @@ makedocs(; sitename="Korg", "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], + linkcheck=true, # check if any external links are broken + linkcheck_timeout=30, # default (10s) is too short for slow academic sites + linkcheck_ignore=[], # maybe don't check ADS links because they like to time out authors="Adam Wheeler and Matthew Abruzzo", format=Documenter.HTML(; assets=["assets/favicon.ico"])) From f91dd4ec44ad2e79eac5ebf27b80fc6f5180ef27 Mon Sep 17 00:00:00 2001 From: Adam Wheeler Date: Tue, 8 Oct 2024 22:22:24 -0400 Subject: [PATCH 2/3] shuffle some low-level things into the devdocs page, fix a couple errors --- docs/make.jl | 11 +++++----- docs/src/API.md | 49 ------------------------------------------ docs/src/devdocs.md | 22 ++++++++++++++----- docs/src/tutorials.md | 4 ++-- src/line_absorption.jl | 5 +++-- src/linelist.jl | 4 ++-- 6 files changed, 29 insertions(+), 66 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index aaeb47f9..8dc3e3a4 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -13,12 +13,11 @@ makedocs(; "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 linkcheck_timeout=30, # default (10s) is too short for slow academic sites linkcheck_ignore=[], # maybe don't check ADS links because they like to time out - authors="Adam Wheeler and Matthew Abruzzo", - format=Documenter.HTML(; assets=["assets/favicon.ico"])) - -deploydocs(; repo="github.com/ajwheeler/Korg.jl.git", - devbranch="main") + 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") diff --git a/docs/src/API.md b/docs/src/API.md index 2dd56cc0..d55e9c38 100644 --- a/docs/src/API.md +++ b/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 diff --git a/docs/src/devdocs.md b/docs/src/devdocs.md index 47ffa9d7..a484ab8b 100644 --- a/docs/src/devdocs.md +++ b/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] ``` diff --git a/docs/src/tutorials.md b/docs/src/tutorials.md index 124d05d2..a5810bcb 100644 --- a/docs/src/tutorials.md +++ b/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. diff --git a/src/line_absorption.jl b/src/line_absorption.jl index 8d0d20cf..54e8b04d 100644 --- a/src/line_absorption.jl +++ b/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. diff --git a/src/linelist.jl b/src/linelist.jl index feb3c43f..5ed35999 100644 --- a/src/linelist.jl +++ b/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. From f8d5fabd6e7cafd341d8a48b3e53a10511d00bb7 Mon Sep 17 00:00:00 2001 From: Adam Wheeler Date: Wed, 9 Oct 2024 09:22:41 -0400 Subject: [PATCH 3/3] don't freak out if MARCS page doesn't work --- docs/make.jl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/make.jl b/docs/make.jl index 8dc3e3a4..442cf7f2 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -15,7 +15,8 @@ makedocs(; "Developer Documentation" => "devdocs.md"], linkcheck=true, # check if any external links are broken linkcheck_timeout=30, # default (10s) is too short for slow academic sites - linkcheck_ignore=[], # maybe don't check ADS links because they like to time out + # 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