You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+72-77Lines changed: 72 additions & 77 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,80 +4,64 @@
4
4
5
5
### MacOS
6
6
7
-
#### Cloning the repo
7
+
#### Software dependencies
8
8
9
-
First, you will need the stochtree repo on your local machine.
10
-
Navigate to the `documentation` repo in your terminal (*replace `~/path/to/documentation` with the path to the documentation repo on your local system*).
9
+
You'll need to have the following software installed
11
10
12
-
```{bash}
13
-
cd ~/path/to/documentation
14
-
```
15
-
16
-
Now, recursively clone the main `stochtree` repo into a `stochtree_repo` subfolder of the `documentation` repo
- Python: can be installed via [homebrew](https://formulae.brew.sh/formula/python@3.14), [conda](https://www.anaconda.com/download), and [directly from the python site](https://www.python.org/downloads/)
12
+
- R: can be installed via [CRAN](https://cran.r-project.org/) or [homebrew](https://formulae.brew.sh/formula/r)
13
+
- Quarto: can be installed [directly from the Quarto site](https://quarto.org/docs/get-started/) or [homebrew](https://formulae.brew.sh/cask/quarto)
14
+
- Doxygen: can be installed [directly from the Doxygen site](https://www.doxygen.nl/) or [homebrew](https://formulae.brew.sh/formula/doxygen)
23
15
24
-
The docs are largely built using [`mkdocs`](https://www.mkdocs.org), [`pkgdown`](https://pkgdown.r-lib.org) and [`doxygen`](https://www.doxygen.nl/index.html),
25
-
with everything tied together using the ["Material for MkDocs"](https://squidfunk.github.io/mkdocs-material/) theme.
16
+
#### Setting up R and Python build dependencies
26
17
27
-
We first create a virtual environment and install the dependencies for `stochtree` as well as the doc site (several python packages: `mkdocs-material`, `mkdocstrings-python`, and `mkdocs-jupyter`).
18
+
Building multi-lingual (R and Python) vignettes requires installing the vignettes' package dependencies. In Python, this is done via a virtual environment (local `.venv`)
Now, we build the `stochtree` python library locally in the virtual environment activated above
28
+
And in R, this is typically done as a global system install, though you might also consider [`renv`](https://rstudio.github.io/renv/) for managing project-specific R dependencies
To use `pkgdown`, you need to install [R](https://cran.r-project.org).
49
-
One R is installed, make sure the dependendencies of the pkgdown build are installed
37
+
Building the R API docs (roxygen2 / pkgdown) and C++ API docs (Doxygen) requires the stochtree source. Clone it into `stochtree_repo/` at the repo root:
`cran-bootstrap.R 0 1 0` prepares a `stochtree_cran/` subdirectory with the pkgdown config but without vignette source (vignettes are served by the Quarto site instead). `cran-cleanup.R` removes that temporary directory when done. The output is written to `docs/R_docs/pkgdown/`.
74
59
75
-
First, ensure that you have [doxygen](https://www.doxygen.nl/index.html) installed.
76
-
On MacOS, this can be [done via homebrew](https://formulae.brew.sh/formula/doxygen) (i.e. `brew install doxygen`).
60
+
#### Building the Doxygen site for the C++ API
77
61
78
-
Then, modify the `Doxyfile` to build the C++ documentation as desired and build the doxygen site
62
+
With the stochtree repo checked out and Doxygen installed (`brew install doxygen` on macOS), run:
79
63
80
-
```{bash}
64
+
```bash
81
65
sed -i '''s|^OUTPUT_DIRECTORY *=.*|OUTPUT_DIRECTORY = ../docs/cpp_docs/|' stochtree_repo/Doxyfile
82
66
sed -i '''s|^GENERATE_XML *=.*|GENERATE_XML = NO|' stochtree_repo/Doxyfile
83
67
sed -i '''s|^GENERATE_HTML *=.*|GENERATE_HTML = YES|' stochtree_repo/Doxyfile
@@ -87,47 +71,58 @@ doxygen Doxyfile
87
71
cd ..
88
72
```
89
73
90
-
### Copying Jupyter notebook demos to the docs directory
74
+
The output is written to `docs/cpp_docs/doxygen/`.
The vignettes live in the `vignettes/` directory and are configured as a standalone Quarto website via `vignettes/_quarto.yml`. Each `.qmd` file uses `{.panel-tabset group="language"}` tabsets to present R and Python code side-by-side. Python cells are executed via `reticulate`; set the `RETICULATE_PYTHON` environment variable to point at your `.venv` interpreter if it isn't picked up automatically.
To preview the vignette site locally with live reload:
122
95
123
-
To build and preview the site locally, run
96
+
```bash
97
+
cd vignettes
98
+
quarto preview
99
+
```
124
100
125
-
```{bash}
126
-
mkdocs serve
101
+
The rendered site is written to `vignettes/_site/`. Individual vignettes use `freeze: auto` in their frontmatter, so re-renders only re-execute cells whose source has changed. To force a full re-execution, delete `vignettes/_freeze/` before rendering.
102
+
103
+
#### Regenerating the Python API reference pages
104
+
105
+
The `python-api/reference/*.qmd` files are generated by quartodoc from the stochtree package's docstrings. They are checked into the repo, so a normal `quarto render` will render whatever is already there. If you've updated docstrings in the stochtree Python package, regenerate them first:
106
+
107
+
```bash
108
+
source .venv/bin/activate
109
+
quartodoc build
127
110
```
128
111
129
-
To build the files underlying the static site, run
112
+
This reads the `quartodoc:` block in `_quarto.yml` and writes updated `.qmd`files to `python-api/reference/`. Run it from the repo root. After regenerating, commit the updated `.qmd` files and run`quarto render` as normal.
130
113
131
-
```{bash}
132
-
mkdocs build
114
+
The CI workflow always runs `quartodoc build` before `quarto render` so the live site stays in sync with the latest package docstrings.
115
+
116
+
### Building the overall website
117
+
118
+
The full site (vignettes + Python API reference + embedded pkgdown/Doxygen) is built from the repo root with:
119
+
120
+
```bash
121
+
quarto render
133
122
```
123
+
124
+
This requires pkgdown and Doxygen output to already exist at `docs/R_docs/pkgdown/` and `docs/cpp_docs/doxygen/` respectively (the CI workflow builds these before running `quarto render`). For iterating on vignettes alone, the `cd vignettes && quarto render` workflow described above is faster.
125
+
126
+
**Freeze cache note:** The vignette `.qmd` files use `freeze: auto`, so re-renders only re-execute cells whose source has changed. The freeze cache lives at `_freeze/vignettes/` (top-level render) or `vignettes/_freeze/` (standalone vignette render). If you switch between the two render modes, copy the cache to the appropriate location before rendering to avoid unnecessary re-execution.
127
+
128
+
The CI workflow (`.github/workflows/docs.yml`) handles the full build and deploys the output `_site/` directory to the `gh-pages` branch.
0 commit comments