Update Julia doc to cross link, remove mention of Artifact (#228)

* Update Julia doc to cross link, remove mention of Artifact

* Fix silly case in download.jl

* Fix R version example

* Bump cache key for macos update

* Try without llvm

docs/conf.py

@@ -18,7 +18,9 @@
 
 import bridgestan
 
-version = os.getenv("BS_DOCS_VERSION", 'v' + bridgestan.__version__)
+
+most_recent_release = 'v' + bridgestan.__version__
+version = os.getenv("BS_DOCS_VERSION", most_recent_release)
 if version == "latest":
     # don't display a version number for "latest" docs
     switcher_version = "latest"
@@ -46,6 +48,11 @@
 myst_enable_extensions = [
     "substitution"
 ]
+myst_substitutions = {
+    "most_recent_release": most_recent_release
+}
+
+suppress_warnings = ["myst.xref_missing"] # Julia doc generates raw html links
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md"]

docs/languages/r.md

@@ -18,7 +18,7 @@ remotes::install_github("https://github.com/roualdes/bridgestan", subdir="R")
 ```
 
 To install a specific version of BridgeStan you can use the argument `ref`,
-for example, {{ "`ref=\"vVERSION\"`".replace("VERSION", env.config.version) }}.
+for example, {{ "`ref=\"VERSION\"`".replace("VERSION", most_recent_release) }}.
 
 The first time you compile a model, the BridgeStan source code for your current version
 will be downloaded and placed in :file:`~/.bridgestan/`.

julia/docs/src/julia.md

@@ -21,7 +21,7 @@ BridgeStan is registered on JuliaRegistries each release.
 ```
 
 The first time you compile a model, the BridgeStan source code for your current version
-will be downloaded as an [Artifact](https://pkgdocs.julialang.org/v1/artifacts/). If you
+will be downloaded to a hidden directory in the users `HOME` directory. If you
 prefer to use a source distribution of BridgeStan, consult the following section.
 
 Note that the system pre-requisites from the [Getting Started guide](../getting-started.rst)

julia/src/compile.jl

@@ -25,7 +25,7 @@ If the environment variable `BRIDGESTAN` is set, this will be returned.
 Otherwise, this function downloads a matching version of BridgeStan under
 a folder called `.bridgestan` in the user's home directory.
 
-See `set_bridgestan_path!()` to set the path from within Julia.
+See [`set_bridgestan_path!()`](@ref) to set the path from within Julia.
 """
 function get_bridgestan_path()
     path = get(ENV, "BRIDGESTAN", "")
@@ -74,7 +74,7 @@ enables the model's threading capabilities. If the same flags are defined in `ma
 the versions passed here will take precedent.
 
 This function checks that the path to BridgeStan is valid and will error if it is not.
-This can be set with `set_bridgestan_path!()`.
+This can be set with [`set_bridgestan_path!()`](@ref).
 """
 function compile_model(
     stan_file::AbstractString;

julia/src/download.jl

@@ -7,8 +7,6 @@ function get_home()
     if Sys.iswindows()
         if haskey(ENV, "USERPROFILE")
             userhome = ENV["USERPROFILE"]
-        elseif !haskey(ENV, "HOMEPATH")
-            userhome = path
         else
             drive = get(ENV, "HOMEDRIVE", "")
             userhome = joinpath(drive, ENV["HOMEPATH"])

julia/src/model.jl

@@ -23,7 +23,7 @@ If lib is a path to a file ending in `.stan`, this will first compile
 the model.  Compilation occurs if no shared object file exists for the
 supplied Stan file or if a shared object file exists and the Stan file
 has changed since last compilation.  This is equivalent to calling
-`compile_model` and then the constructor of `StanModel`. If `warn` is
+[`compile_model`](@ref) and then the constructor of `StanModel`. If `warn` is
 false, the warning about re-loading the same shared objects is suppressed.
 
 Data should either be a string containing a JSON string literal, a
@@ -102,8 +102,8 @@ end
 
 Construct a StanRNG instance from a `StanModel` instance and a seed.
 
-This can be used in the `param_constrain` and `param_constrain!` methods
-when using the generated quantities block.
+This can be used in the [`param_constrain`](@ref) and
+[`param_constrain!`](@ref) methods when using the generated quantities block.
 
 This object is not thread-safe, one should be created per thread.
 """
@@ -144,7 +144,7 @@ end
 Construct a StanRNG instance from a `StanModel` instance and a seed.  This
 function is a wrapper around the constructor `StanRNG`.
 
-This can be used in the `param_constrain` and `param_constrain!` methods
+This can be used in the [`param_constrain`](@ref) and [`param_constrain!`](@ref) methods
 when using the generated quantities block.
 
 The StanRNG object created is not thread-safe, one should be created per thread.
@@ -266,9 +266,9 @@ If `include_gq` is `true`, then `rng` must be provided.
 See `StanRNG` for details on how to construct RNGs.
 
 The result is stored in the vector `out`, and a reference is returned. See
-`param_constrain` for a version which allocates fresh memory.
+[`param_constrain`](@ref) for a version which allocates fresh memory.
 
-This is the inverse of `param_unconstrain!`.
+This is the inverse of [`param_unconstrain!`](@ref).
 """
 function param_constrain!(
     sm::StanModel,
@@ -318,13 +318,13 @@ Additionally (if `include_tp` and `include_gq` are set, respectively)
 returns transformed parameters and generated quantities.
 
 If `include_gq` is `true`, then `rng` must be provided.
-See `StanRNG` for details on how to construct RNGs.
+See [`StanRNG`](@ref) for details on how to construct RNGs.
 
 This allocates new memory for the output each call.
-See `param_constrain!` for a version which allows
+See [`param_constrain!`](@ref) for a version which allows
 re-using existing memory.
 
-This is the inverse of `param_unconstrain`.
+This is the inverse of [`param_unconstrain`](@ref).
 """
 function param_constrain(
     sm::StanModel,
@@ -350,12 +350,13 @@ end
 Returns a vector of unconstrained params give the constrained parameters.
 
 It is assumed that these will be in the same order as internally represented by the model (e.g.,
-in the same order as `param_names(sm)`). If structured input is needed, use `param_unconstrain_json!`
+in the same order as [`param_names()`](@ref)).
+If structured input is needed, use [`param_unconstrain_json!`](@ref)
 
 The result is stored in the vector `out`, and a reference is returned. See
-`param_unconstrain` for a version which allocates fresh memory.
+[`param_unconstrain`](@ref) for a version which allocates fresh memory.
 
-This is the inverse of `param_constrain!`.
+This is the inverse of [`param_constrain!`](@ref).
 """
 function param_unconstrain!(sm::StanModel, theta::Vector{Float64}, out::Vector{Float64})
     dims = param_unc_num(sm)
@@ -385,13 +386,14 @@ end
 Returns a vector of unconstrained params give the constrained parameters.
 
 It is assumed that these will be in the same order as internally represented by the model (e.g.,
-in the same order as `param_unc_names(sm)`). If structured input is needed, use `param_unconstrain_json`
+in the same order as [`param_unc_names()`](@ref)).
+If structured input is needed, use [`param_unconstrain_json`](@ref)
 
 This allocates new memory for the output each call.
-See `param_unconstrain!` for a version which allows
+See [`param_unconstrain!`](@ref) for a version which allows
 re-using existing memory.
 
-This is the inverse of `param_constrain`.
+This is the inverse of [`param_constrain`](@ref).
 """
 function param_unconstrain(sm::StanModel, theta::Vector{Float64})
     out = zeros(param_unc_num(sm))
@@ -406,7 +408,7 @@ This accepts a JSON string of constrained parameters and returns the unconstrain
 The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html).
 
 The result is stored in the vector `out`, and a reference is returned. See
-`param_unconstrain_json` for a version which allocates fresh memory.
+[`param_unconstrain_json`](@ref) for a version which allocates fresh memory.
 """
 function param_unconstrain_json!(sm::StanModel, theta::String, out::Vector{Float64})
     dims = param_unc_num(sm)
@@ -439,7 +441,7 @@ This accepts a JSON string of constrained parameters and returns the unconstrain
 The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html).
 
 This allocates new memory for the output each call.
-See `param_unconstrain_json!` for a version which allows
+See [`param_unconstrain_json!`](@ref) for a version which allows
 re-using existing memory.
 """
 function param_unconstrain_json(sm::StanModel, theta::String)
@@ -487,7 +489,7 @@ This calculation drops constant terms that do not depend on the parameters if `p
 and includes change of variables terms for constrained parameters if `jacobian` is `true`.
 
 The gradient is stored in the vector `out`, and a reference is returned. See
-`log_density_gradient` for a version which allocates fresh memory.
+[`log_density_gradient`](@ref) for a version which allocates fresh memory.
 """
 function log_density_gradient!(
     sm::StanModel,
@@ -529,9 +531,8 @@ Returns a tuple of the log density and gradient of the specified unconstrained p
 This calculation drops constant terms that do not depend on the parameters if `propto` is `true`
 and includes change of variables terms for constrained parameters if `jacobian` is `true`.
 
-
 This allocates new memory for the gradient output each call.
-See `log_density_gradient!` for a version which allows
+See [`log_density_gradient!`](@ref) for a version which allows
 re-using existing memory.
 """
 function log_density_gradient(
@@ -554,7 +555,7 @@ and includes change of variables terms for constrained parameters if `jacobian`
 
 The gradient is stored in the vector `out_grad` and the
 Hessian is stored in `out_hess` and references are returned. See
-`log_density_hessian` for a version which allocates fresh memory.
+[`log_density_hessian`](@ref) for a version which allocates fresh memory.
 """
 function log_density_hessian!(
     sm::StanModel,
@@ -605,7 +606,7 @@ This calculation drops constant terms that do not depend on the parameters if `p
 and includes change of variables terms for constrained parameters if `jacobian` is `true`.
 
 This allocates new memory for the gradient and Hessian output each call.
-See `log_density_gradient!` for a version which allows
+See [`log_density_hessian!`](@ref) for a version which allows
 re-using existing memory.
 """
 function log_density_hessian(
@@ -630,7 +631,7 @@ This calculation drops constant terms that do not depend on the parameters if `p
 and includes change of variables terms for constrained parameters if `jacobian` is `true`.
 
 The product is stored in the vector `out` and a reference is returned. See
-`log_density_hessian_vector_product` for a version which allocates fresh memory.
+[`log_density_hessian_vector_product`](@ref) for a version which allocates fresh memory.
 """
 function log_density_hessian_vector_product!(
     sm::StanModel,
@@ -676,7 +677,8 @@ This calculation drops constant terms that do not depend on the parameters if `p
 and includes change of variables terms for constrained parameters if `jacobian` is `true`.
 
 This allocates new memory for the output each call. See
-`log_density_hessian_vector_product!` for a version which allows re-using existing memory.
+[`log_density_hessian_vector_product!`](@ref) for a version which allows re-using
+existing memory.
 """
 function log_density_hessian_vector_product(
     sm::StanModel,
@@ -689,11 +691,6 @@ function log_density_hessian_vector_product(
     log_density_hessian_vector_product!(sm, q, v, out; propto = propto, jacobian = jacobian)
 end
 
-"""
-    log_density_hessian_vector_product(sm, q, v; propto=true, jacobian=true)
-"""
-
-
 """
     handle_error(lib::Ptr{Nothing}, err::Ref{Cstring}, method::String)
 

julia/test/util_tests.jl

@@ -26,7 +26,7 @@ end
 
 
 
-@testset "download artifact" begin
+@testset "download" begin
     withenv("BRIDGESTAN" => nothing) do
         BridgeStan.validate_stan_dir(BridgeStan.get_bridgestan_path())
     end