Doc: updates following Rust compilation (#231)

* Doc: updates following Rust compilation

* Wording tweaks

R/R/bridgestan.R

@@ -152,11 +152,11 @@ StanModel <- R6::R6Class("StanModel",
     },
     #' @description
     #' Returns a vector of constrained parameters given the unconstrained parameters.
-    #' See also `StanModel$param_unconstrain()`, the inverse of this function.
+    #' See also [StanModel$param_unconstrain()], the inverse of this function.
     #' @param theta_unc The vector of unconstrained parameters.
     #' @param include_tp Whether to also output the transformed parameters of the model.
     #' @param include_gq Whether to also output the generated quantities of the model.
-    #' @param rng The random number generator to use if `include_gq` is `TRUE`.  See `StanModel$new_rng()`.
+    #' @param rng The random number generator to use if `include_gq` is `TRUE`.  See [StanModel$new_rng()].
     #' @return The constrained parameters of the model.
     param_constrain = function(theta_unc, include_tp = FALSE, include_gq = FALSE, rng) {
       if (missing(rng)) {
@@ -184,7 +184,7 @@ StanModel <- R6::R6Class("StanModel",
       vars$theta
     },
     #' @description
-    #' Create a new persistent PRNG object for use in `param_constrain()`.
+    #' Create a new persistent PRNG object for use in [param_constrain()].
     #' @param seed The seed for the PRNG.
     #' @return A `StanRNG` object.
     new_rng = function(seed) {
@@ -194,9 +194,9 @@ StanModel <- R6::R6Class("StanModel",
     #' Returns a vector of unconstrained parameters 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 `StanModel$param_names()`).
-    #' If structured input is needed, use `StanModel$param_unconstrain_json()`.
-    #' See also `StanModel$param_constrain()`, the inverse of this function.
+    #' the model (e.g., in the same order as [StanModel$param_names()]).
+    #' If structured input is needed, use [StanModel$param_unconstrain_json()].
+    #' See also [StanModel$param_constrain()], the inverse of this function.
     #' @param theta The vector of constrained parameters.
     #' @return The unconstrained parameters of the model.
     param_unconstrain = function(theta) {
@@ -353,7 +353,7 @@ handle_error <- function(lib_name, err_msg, err_ptr, function_name) {
 
 #' StanRNG
 #'
-#' RNG object for use with `StanModel$param_constrain()`
+#' RNG object for use with [StanModel$param_constrain()]
 #' @field ptr The pointer to the RNG object.
 #' @keywords internal
 StanRNG <- R6::R6Class("StanRNG",

R/R/compile.R

@@ -34,7 +34,7 @@ set_bridgestan_path <- function(path) {
 #' a matching version of BridgeStan to a folder called
 #' `.bridgestan` in the user's home directory.
 #'
-#' @seealso [set_bridgestan_path]
+#' @seealso [set_bridgestan_path()]
 get_bridgestan_path <- function() {
     # try to get from environment
     path <- Sys.getenv("BRIDGESTAN", unset = "")

README.md

@@ -103,7 +103,7 @@ We are aware of the following projects using BridgeStan.
 ## Research using BridgeStan
 
 If you use BridgeStan in your research, please consider citing [our JOSS paper](https://joss.theoj.org/papers/10.21105/joss.05236)
-and letting us know so we list your project here.
+and letting us know so we can list your project here.
 
 - [*Verified Density Compilation for a Probabilistic Programming Language*](https://doi.org/10.1145/3591245)
 - [*Variational Inference with Gaussian Score Matching*](https://arxiv.org/pdf/2307.07849.pdf)

docs/getting-started.rst

@@ -19,7 +19,8 @@ Downloading BridgeStan
 
 .. note::
     The :doc:`Julia <languages/julia>`, :doc:`Python <languages/python>`, and :doc:`R <languages/r>`
-    interfaces will download the source for you the first time you compile a model.
+    interfaces will download the source for you the first time you compile a model, and the :doc:`Rust <languages/rust>`
+    interface has an optional feature to download the source upon request.
     This section is optional for users primarily interested in those interfaces.
 
 

docs/index.rst

@@ -1,14 +1,14 @@
 
-Welcome to BridgeStan's documentation!
-======================================
+BridgeStan -- efficient, in-memory access to the methods of a Stan model
+========================================================================
 
-BridgeStan provides efficient in-memory access through Python, Julia,
-R, and Rust to the methods of a `Stan <https://mc-stan.org>`__ model, including
-log densities, gradients, Hessians, and constraining and unconstraining
-transforms.
+BridgeStan is a library (with :doc:`bindings <languages>` available in Python,
+Julia, R, and Rust) that grants access to the methods of a `Stan <https://mc-stan.org>`__
+model, including log densities, gradients, Hessians, and constraining and
+unconstraining transforms.
 
-The motivation is developing inference algorithms in
-higher-level languages for arbitrary Stan models, such as those in
+This allows researchers and library authors to develop inference algorithms in
+higher-level languages and apply them to arbitrary Stan models, such as those in
 `posteriordb <https://github.com/stan-dev/posteriordb>`__.
 
 

docs/languages.rst

@@ -8,11 +8,11 @@ written in C.
 
 All language interfaces expose the same core functionality from the
 :doc:`C API <./languages/c-api>`.
-Additional "quality of life" features such as the ability to download
-BridgeStan's source code automatically or compile models from inside the language
-(rather than manually calling :command:`make`) are available on a best-effort basis.
-If you are missing these features in your favorite language, we would welcome a
-`contribution <https://github.com/roualdes/bridgestan/blob/main/CONTRIBUTING.md>`__!
+
+
+Additional "quality of life" features are available on a best-effort basis.
+If BridgeStan's bindings to your favorite language are missing one of these features, we welcome
+`contributions <https://github.com/roualdes/bridgestan/blob/main/CONTRIBUTING.md>`__!
 
 .. toctree::
     :maxdepth: 2