Start using sphinxcontrib-rust for Rust API documentation (#264)

* Start using sphinxcontrib-rust

* Better links

* Try Model::

* Bump ci python

* Fix links

* Bump sphinxcontrib-rust

* Typo fix

* Bump sphinxcontrib-rust

* Typo fix

.github/workflows/docs.yaml

@@ -31,10 +31,10 @@ jobs:
         with:
           submodules: recursive
 
-      - name: Set up Python 3.9
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: 3.9
+          python-version: 3.11
 
       - name: Install dependencies (python)
         run: |

R/DESCRIPTION

@@ -8,7 +8,7 @@ Description: BridgeStan provides efficient in-memory access to the methods of a
     including log densities, gradients, Hessians, and constraining and unconstraining
     transforms.
 Encoding: UTF-8
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 Roxygen: list(markdown = TRUE, r6 = TRUE)
 Suggests:
     testthat (>= 3.0.0),

R/R/bridgestan.R

@@ -223,7 +223,7 @@ StanModel <- R6::R6Class("StanModel",
     #' @description
     #' This accepts a JSON string of constrained parameters and returns the unconstrained parameters.
     #'
-    #' The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html).
+    #' The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json_apdx.html).
     #' @param json Character vector containing a string representation of JSON data.
     #' @return The unconstrained parameters of the model.
     param_unconstrain_json = function(json) {

docs/conf.py

@@ -19,7 +19,7 @@
 import bridgestan
 
 
-most_recent_release = '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
@@ -45,17 +45,13 @@
     "myst_parser",
 ]
 
-myst_enable_extensions = [
-    "substitution"
-]
-myst_substitutions = {
-    "most_recent_release": most_recent_release
-}
+myst_enable_extensions = ["substitution"]
+myst_substitutions = {"most_recent_release": most_recent_release}
 
-suppress_warnings = ["myst.xref_missing"] # Julia doc generates raw html links
+suppress_warnings = ["myst.xref_missing"]  # Julia doc generates raw html links
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md", "languages/_*"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -131,7 +127,7 @@
 
 autoclass_content = "both"
 
-# Julia and C++ doc build
+# Other languages doc build
 import os
 import subprocess
 import pathlib
@@ -161,15 +157,15 @@
     )
 
     # delete some broken links in the generated R docs
-    StanModel = (pathlib.Path(__file__).parent / "languages" / "_r" / "StanModel.md")
+    StanModel = pathlib.Path(__file__).parent / "languages" / "_r" / "StanModel.md"
     text = StanModel.read_text()
     start = text.find("### Public methods")
     end = text.find("### Method `")
     text = text[:start] + text[end:]
     StanModel.write_text(text)
 
     # replaces the headers with more appropriate levels for embedding
-    for f in (pathlib.Path(__file__).parent / "languages" / "_r" ).iterdir():
+    for f in (pathlib.Path(__file__).parent / "languages" / "_r").iterdir():
         text = f.read_text()
         text = re.sub(r"(#+) ", r"##\1 ", text)
         f.write_text(text)
@@ -195,3 +191,23 @@
         exclude_patterns += ["languages/c-api.rst"]
 else:
     extensions.append("breathe")
+
+
+try:
+    print("Checking Rust doc availability")
+    subprocess.run(["cargo", "--version"], check=True, capture_output=True)
+except Exception as e:
+    if RUNNING_IN_CI:
+        raise e
+    else:
+        print("Rust not installed, skipping Rust Doc")
+        exclude_patterns += ["languages/rust.md", "languages/_rust"]
+else:
+    extensions.append("sphinxcontrib_rust")
+    myst_enable_extensions += ["colon_fence", "attrs_block"]
+    rust_crates = {
+        "bridgestan": str(pathlib.Path(__file__).parent.parent / "rust"),
+    }
+    rust_doc_dir = "languages/_rust"
+    rust_rustdoc_fmt = "md"
+    rust_generate_mode = "changed" if not RUNNING_IN_CI else "always"

docs/languages/_r/StanModel.md

@@ -314,7 +314,7 @@ The unconstrained parameters of the model.
 
 This accepts a JSON string of constrained parameters and returns the unconstrained parameters.
 
-The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html).
+The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json_apdx.html).
 
 ###### Usage