#Editing the OHDSI GIS WG documentation website
We encourage contributions to our software documentation and our website. Follow these guidelines for making and proposing changes.
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 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.
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.
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.