#Editing the OHDSI GIS WG documentation website

Overview

We encourage contributions to our software documentation and our website. Follow these guidelines for making and proposing changes.

Website

This section explains how to edit the content of the website. In this context, the website refers to everything at https://ohdsi.github.io/GIS/ except for the https://ohdsi.github.io/GIS/gaiaCore content which is covered in the next section.

The source of the website’s content are contained in the ./rmd/ directory at the root of this repository. Most of the content in the ./rmd/ directory are RMarkdown files which are rendered to HTML, stored in the ./docs/ directory, and served as a website using GitHub Pages. Along with RMD files, there are images, stylesheets (CSS), and a file called _site.yml. The _site.yml file specifies the website structure and defines the elements on the site’s navbar.

To edit existing pages on the website, simply find and edit the corresponding RMD file. To add new pages to the website, create an RMD file, fill it with content, and then add it to _site.yml in a fitting place. Whether you are editing existing pages or creating new ones, the function RMarkdown::render_site() can be run to regenerate the HTML files docs directory. More on rendering below.

R Package Documentation

R Package documentation is created using ROxygen within R scripts. The ROxygen is rendered to .Rd files by running devtools::document(). After documentation is created, the function pkgdown::build_site() can be run to render the .Rd files into HTML, which automatically ends up in ./docs/gaiaCore/ and can be accessed from the website. More on rendering below.

Rendering

If you’ve been keeping track, there are three functions which need to be called to generate the HTML for the website: 1. devtools::document() creates .Rd files from inline ROxygen 2. RMarkdown::render_site() creates HTML for website content 3. pkgdown::build_site() creates HTML for the R Package documentation

Running three functions each time you need to regenerate the website can be a drag. Even worse, the website won’t generate correctly if they are run out of order.

To make things easier, there is a helper R script, render_gaia_site.R, that can be run using source('./render_gaia_site.R'). This simply calls those three functions in the correct order. It makes life just a bit easier.

Publishing

Finally, after changes have been made to the website or documentation and the new HTML has been rendered, simply commit your changes and create a Pull Request on the OHDSI GIS WG repository. A maintainer will review your changes, provide feedback if necessary, and accept your changes when they are ready.