RStudio User Guide

Source code: https://github.com/rstudio/rstudio-pro/tree/main/docs/user/rstudio

Development

Install Quarto.

Download the CLI here
Install the Quarto R Package with install.packages(“quarto”)

Clone rstudio-pro
Open up rstudio-pro/docs/user/rstudio in your favorite IDE.

There is an Rproj file in rstudio-pro/docs/user/rstudio.

Serve the project.

From RStudio, enter quarto::quarto_preview()
From the command line, quarto preview from within the rstudio-pro/docs/user/rstudio directory This will serve the site to your web browser. Quarto will detect when you make changes to any of the qmd files and rerender that page. An exception to this is if the page contains code - Quarto will not rerender this during quarto serve. You need to render it manually with quarto render file_name.qmd (on the command line) or quarto_render("file_name.qmd") (in R). Note that you do not need to stop the server while doing this.

Here’s how to work with the docs in this folder:

Testing the build locally

In order to test that the Jenkinsfile build works properly, do the following.

Generate _quarto.yml and _variables.yml

cd docs
docker build --tag rstudio/docs .
cd user/rstudio
docker run -it --mount type=bind,source="$(pwd)",target=/app rstudio/docs bash
cd app
RSTUDIO_BUILD_TYPE=Dev RSTUDIO_VERSION_MAJOR=2022 RSTUDIO_VERSION_MINOR=11 RSTUDIO_VERSION_PATCH=0 RSTUDIO_VERSION_SUFFIX=-dev+999.pro1 cmake .

Note that the cmake command needs to be run in the docs/user/rstudio folder.

This command populates the version number that appears in the final docs. Feel free to change the various RSTUDIO_* variables. The final version number will be made from these variables and will show up in _variables.yml and _quarto.yml.

Run the build

Afterwards, exit the container, reenter the container from the project root directory, and cd back to the Quarto docs directory before running make to mimic the build pipeline on Jenkins:

## Exit container & cd to root directory in order to test build in proper directory
cd ../../..
docker run -it --mount type=bind,source="$(pwd)",target=/app rstudio/docs bash
cd app/docs/user/rstudio
make build

Test internal docs links

Links and references to pages and sections in the docs can be easy to break if you change the title of a section and it doesn’t have an ID assigned to it. This creates a broken link that can be difficult to notice until the docs are already published. To test your changes and look for any newly broken links you can run either make test, or just make to build and check for broken links.

Broken links are also checked on doc builds. If your PR broke a link, it’s your responsibility to fix it.

Testing against the build server

You can run pro-docs-pipeline against your branch by going to the Jenkins Dashboard and putting the name of your branch in the branch_name field (and the git_revision build to be safe)

Requirements

The user guide site is built using Quarto. Download the latest version of Quarto from https://quarto.org/docs/get-started/

Preview locally

To preview the user guide locally first make sure you are in the ./docs/user/rstudio directory. Then preview the site using the quarto preview command.

cd docs/user/rstudio
quarto preview