Start online docs, based on BridgeStan's setup (#29)

.github/workflows/docs.yaml

@@ -0,0 +1,115 @@
+name: Build TinyStan docs
+
+on:
+  push:
+    branches:
+      - 'main'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version of TinyStan docs to build'
+        required: false
+        type: string
+        default: ''
+  workflow_call:
+    inputs:
+      version:
+        description: 'Version of TinyStan docs to build'
+        required: true
+        type: string
+  release:
+    types: [published]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - name: Check out github
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9
+
+      - name: Install dependencies (python)
+        run: |
+          python -m pip install --upgrade pip wheel
+          python -m pip install --upgrade -r docs/requirements.txt
+
+      - name: Install os dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install pandoc doxygen -y
+
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@v2
+
+
+      - name: Install R
+        uses: r-lib/actions/[email protected]
+
+      - name: Install R dependencies
+        uses: r-lib/actions/[email protected]
+        with:
+          packages: |
+            any::roxygen2
+            github::Genentech/rd2markdown
+
+      - name: Install packages
+        run: |
+          cd clients/python/
+          pip install .
+          cd ../julia
+          julia --project=./docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+          cd ../R/
+          Rscript -e "install.packages(getwd(), repos=NULL, type=\"source\")"
+
+      - name: Calculate version
+        if:
+        run: |
+          if [[ "${{ inputs.version }}" != "" ]]; then
+            echo "TS_DOCS_VERSION=${{ inputs.version }}" >> $GITHUB_ENV
+          else
+            echo "TS_DOCS_VERSION=latest" >> $GITHUB_ENV
+          fi
+
+      - name: Build docs
+        run: |
+          cd docs/
+          export TS_DOCS_VERSION=$TS_DOCS_VERSION
+          make html
+
+      - name: Check out github
+        uses: actions/checkout@v4
+        with:
+          path: docs/_build/ts-docs
+          ref: gh-pages
+
+      - name: Commit html docs
+        run: |
+          cd docs/_build/
+
+          ls
+
+          rm -rf ts-docs/$TS_DOCS_VERSION
+          cp -r html ts-docs/$TS_DOCS_VERSION
+
+          cd ts-docs/
+          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+          git add .
+          git commit --amend -m "Rebuild docs"
+
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          branch: gh-pages
+          directory: docs/_build/ts-docs
+          force: true
+

.gitignore

@@ -5,6 +5,7 @@ test_models/**/*.hpp
 
 bin/
 _build/
+build/
 .coverage
 
 make/local

TODO.md

@@ -17,7 +17,7 @@
 - [x] Language specific outputs (rvars, stanio, not sure if Julia has a good option)
 
 ## Testing
-- [ ] Test with sanitizers in CI?
+- [-] Test with sanitizers in CI?
 - [x] Add a variety of models, including:
     - [x] A model that uses SUNDIALS
     - [x] A model with no parameters
@@ -27,11 +27,11 @@
 
 
 ## Other
-- [ ] Documentation
+- [x] Documentation
 - [x] Set up visibility such that all non-API symbols are hidden
 - [x] Rename
+- [x] Try to compile for webassembly with emscripten
 - [ ] Look into cmake/clang-cl builds
-- [ ] Try to compile for webassembly with emscripten
 
 ## R Package
 

clients/R/convert_docs.R

@@ -0,0 +1,22 @@
+# Converts R documentation (.Rd) files to markdown (.md) files for use in
+# Sphinx.
+
+library(rd2markdown)
+library(roxygen2)
+
+roxygen2::roxygenize()
+
+files <- list.files("man", pattern = "*.Rd")
+
+for (f in files) {
+    name <- substr(f, 1, nchar(f) - 3)
+
+    # read .Rd file and convert to markdown
+    rd <- rd2markdown::get_rd(file = file.path(".", "man", f))
+    md <- rd2markdown::rd2markdown(rd, fragments = c())
+
+    # write it to the docs folder
+    writeLines(md, file.path("..", "..", "docs", "languages", "_r", paste0(name,
+        ".md")))
+
+}

clients/julia/docs/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterMarkdown = "997ab1e6-3595-5248-9280-8efb232c3433"
+TinyStan = "3a8caf9d-1ca3-4bd7-a835-128840ab73a4"

clients/julia/docs/README.md

@@ -0,0 +1,4 @@
+# Julia Interface Docs
+
+We use [DocumenterMarkdown.jl](https://github.com/JuliaDocs/DocumenterMarkdown.jl) to build documentation
+from our source file. This is then copied into the Python docs source tree for use by Sphinx.

clients/julia/docs/make.jl

@@ -0,0 +1,18 @@
+using Documenter, TinyStan
+using DocumenterMarkdown
+
+makedocs(
+    format = Markdown(),
+    repo = "https://github.com/WardBrian/TinyStan/blob/main{path}#{line}",
+)
+
+cp(
+    joinpath(@__DIR__, "build/julia.md"),
+    joinpath(@__DIR__, "../../../docs/languages/julia.md");
+    force = true,
+)
+cp(
+    joinpath(@__DIR__, "build/assets/Documenter.css"),
+    joinpath(@__DIR__, "../../../docs/_static/css/Documenter.css");
+    force = true,
+)

clients/julia/docs/src/julia.md

@@ -0,0 +1,83 @@
+# Julia Interface
+
+```@raw html
+% NB: If you are reading this file in docs/languages, you are reading a generated output!
+% This should be apparent due to the html tags everywhere.
+% If you are reading this in julia/docs/src, you are reading the true source!
+% Please only make edits in the later file, since the first is DELETED each re-build.
+```
+
+---
+
+## Installation
+
+### From Source
+This section assumes you have followed the [Getting Started guide](../getting-started.rst)
+to install TinyStan's pre-requisites and downloaded a copy of the TinyStan source code.
+
+To install the Julia interface, you can either install it directly from Github by running
+the following inside a Julia REPL
+
+```julia
+] add https://github.com/WardBrian/tinystan.git:clients/julia
+```
+
+Or, since you have already downloaded the repository, you can run
+
+```julia
+] dev clients/julia/
+```
+
+from the TinyStan folder.
+
+The first time you compile a model, the BridgeStan source code for your current version
+will be downloaded to a hidden directory in the users `HOME` directory.
+
+To use the TinyStan source you've manually downloaded instead of
+one the package will download for you, you must use
+[`set_tinystan_path()`](TinyStan.set_tinystan_path!) or the `$TINYSTAN`
+environment variable.
+
+Note that the Julia package depends on Julia 1.6+ and the `Inflate` package.
+
+
+
+## Example Program
+
+An example program is provided alongside the Julia interface code in `example.jl`:
+
+
+```@raw html
+<details>
+<summary><a>Show example.jl</a></summary>
+```
+
+```{literalinclude} ../../clients/julia/example.jl
+:language: julia
+```
+
+```@raw html
+</details>
+```
+
+
+## API Reference
+
+### Model interface
+
+```@docs
+Model
+sample
+HMCMetric
+pathfinder
+optimize
+OptimizationAlgorithm
+laplace_sample
+```
+
+### Compilation utilities
+```@docs
+compile_model
+get_tinystan_path
+set_tinystan_path!
+```

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/Documenter.css

@@ -0,0 +1,18 @@
+div.wy-menu-vertical ul.current li.toctree-l3 a {
+  font-weight: bold;
+}
+
+a.documenter-source {
+  float: right;
+}
+
+.documenter-methodtable pre {
+    margin-left: 0;
+    margin-right: 0;
+    margin-top: 0;
+    padding: 0;
+}
+
+.documenter-methodtable pre.documenter-inline {
+    display: inline;
+}

docs/_static/css/custom.css

@@ -0,0 +1,7 @@
+html[data-theme="light"] {
+    --pst-color-inline-code: #008000;
+}
+
+html[data-theme="dark"] {
+    --pst-color-inline-code: #659157;
+}

docs/_static/switcher.json

@@ -0,0 +1,7 @@
+[
+    {
+        "name": "latest",
+        "version": "latest",
+        "url": "https://brianward.dev/tinystan/latest/"
+    }
+]

docs/add_version.py

@@ -0,0 +1,22 @@
+import sys
+import json
+
+
+def new_version(version):
+    return {
+        "name": version,
+        "version": version,
+        "url": f"https://brianward.dev/tinystan/{version}/",
+    }
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python add_version.py <version>")
+        sys.exit(1)
+    version = sys.argv[1]
+    with open("_static/switcher.json", "r") as f:
+        switcher = json.load(f)
+    switcher.insert(1, new_version(version))
+    with open("_static/switcher.json", "w") as f:
+        json.dump(switcher, f, indent=4)