This repository is used to build and store the central documentation for the ropensci-review-tools organization, which contains a suite of tools developed and used by rOpenSci to support their software peer-review processes. The documentation uses readthedocs, and is hosted at ropensci-review-tools.readthedocs.io.

Most of you should just head straight to ropensci-review-tools.readthedocs.io. The rest of this is technical detail on how that site is actually created. It will work only on Linux-type systems. The readthedocs site bundles documentation from all repositories within the ropensci-review-tools organisation, a process executed by the single pkgdocs-script.R file. The readthedocs files all reside in the docs folder of this repository, and can be recreated anew with the following steps:

1. Install the following python packages (pip install or equivalent):

   • sphinx, myst-parser, sphinx-rtd-theme

2. Clone the following repositories from this GitHub organization in a single directory:

   • autotest
   • pkgcheck
   • pkgstats
   • roreviewapi
   • ropensci-review-tools
   • srr

3. Within the directory of this repository (cd ropensci-review-tools), run make clean to remove all of the actual documentation files, leaving only the readthedocs configuration files. That should reduce 300 individual files down to just over ten. (There's even a make count to check those numbers).

4. Type make to rebuild everything.

5. Finally make open will open the locally-generated documentation in your default web browser.

Check out the contents of the makefile to see how it works, or just type make help:

$ make help
all                  The default `make` command = grab + build
build                readthedocs 'make html' command
clean                Run readthedocs 'make clean' + clean all 'grab' targets (R pkg files)
count                count some stuff
grab                 Grab all files from the R packages by calling 'pkgdocs-script'
help                 Show this help
open                 Open the main 'html' page

This site can be updated in response to any changes in any of the respective packages by simply running make. All changes should then be listed in git status, with the exception of any new files which have been added, and are not yet tracked by git. It is thus good practice to either:

1. Run make clean first prior to make, and then git add everything in all sub-directories of docs; or
2. Using git clean -n to list files not tracked by git, and add any *.md files listed in any sub-folders of `docs.

New packages in the ropensci-review-tools GitHub organization can be added to readthedocs site with the following modifications:

1. Add the package name at the top of the pkgdocs-script.R script (and ensure that the repository to be added is locally cloned to the same root directory as this, and all other, repositories).
2. Modify docs/index.rst, and add the main .md file of the new package to the second Table-of-Contents entry (generally as <package/package.md>).
3. Modify the makefile to add the new package name to the make clean step.
4. Run make to automatically compile the package documentation into the /docs folder of this repository.
5. Add the newly compiled sub-folder of /docs to the git tree, commit the files, push to GitHub, and documentation for the the new package will be added to this readthedocs site.