Merge pull request #924 from wadpac/issue923_contributingGithubIO

Contributing guidelines (github.io)
wadpac · Oct 12, 2023 · 9cac3c0 · 9cac3c0
2 parents 0e67881 + a2a9a02
commit 9cac3c0
Show file tree

Hide file tree

Showing 118 changed files with 1,119 additions and 474 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -28,7 +28,7 @@ The sections below outline the steps in each case.
 3. if needed, fork the repository to your own Github profile and create your own feature branch off of the latest master commit. While working on your feature branch, make sure to stay up to date with the master branch by pulling in changes, possibly from the 'upstream' repository (follow the instructions [here](https://help.github.com/articles/configuring-a-remote-for-a-fork/) and [here](https://help.github.com/articles/syncing-a-fork/));
 4. make sure the existing tests still work by running the test suite from RStudio;
 5. add your own tests (if necessary);
-6. update or expand the documentation;
+6. update or expand the documentation, see [package documentation guidelines](#package-documentation);
 7. make sure the release notes in `inst/NEWS.Rd` are updated;
 8. add your name to the contributors lists in the `DESCRIPTION` and `CITATION.cff` files;
 9. push your feature branch to (your fork of) the GGIR repository on GitHub;
@@ -51,6 +51,114 @@ Some general guidelines that we try to adhere to:
 If you are a first time contributor, don't worry about coding style too much.
 We will help you get things in shape.
 
+### Package documentation
+
+We currently have three sources for documenting the package:
+
+- The reference manual, including package basic information and the functions documentation files.
+- The package vignettes.
+- The github.io website (built with the `pkgdown` package).
+
+#### Reference manual
+
+The reference manual gets the information from the .Rd documents within the man
+folder in the package repository. Therefore, updating the information in those
+files will automatically update the reference manual. Note that most of the GGIR
+functions are not intended for direct interaction with the user, as such, the
+documentation of most arguments is centralized in the details section of man/GGIR.Rd. 
+If you for example want to add an extra parameter to `params_247` then this should
+be documented there. Further, you should not forget to include the new argument in
+functions \link{load_params} and \link{check_params}.
+
+#### Package vignettes
+
+The folder vignettes in the GGIR repository contains the .Rmd files. The .Rmd files
+that do not start with the word 'chapter' are used for the traditional package vignettes
+as hosted by CRAN. Use these files to edit an existing vignette, or use the structure
+of any of the vignettes to build up a new one. All .Rmd files which name 
+starts with the word 'chapter' are ignored. These chapter-vignettes are used only for
+the github.io website (see [next section](#github.io-website)).
+
+**To create a new vignette for CRAN**
+
+To create a new package vignette for CRAN, please use `usethis::use_vignette()` and
+make sure the name of the vignette file does not start by "chapter". For example,
+if you want to create a new vignette on sleep for CRAN, you may do the following:
+
+```
+usethis::use_vignette(name = "sleep", 
+                      title = "How to analyse your sleep data in GGIR")
+```
+This would create a new "sleep.Rmd" file within the vignettes folder in the GGIR
+repository. Then you can edit this file to build up the vignette.
+
+**To remove a vignette from CRAN**
+
+There are two ways to remove a vignette from CRAN:
+
+1. Removing the Rmd file corresponding to the vignette in the vignettes folder,
+note that the file and the information will be lost.
+2. Adding the path to the vignette in the .Rbuildignore file available in the
+GGIR repository. For example, to remove the GGIRParameters vignette from CRAN, you
+can add:
+
+```
+^vignettes/GGIRParameters.Rmd
+
+```
+
+#### github.io website
+
+For updating or adding information to the github.io website, we need to use
+[the pkgdown configuration file](_pkgdown.yml) that can be found in the repositories 
+root directory, as well as with the chapter vignettes discussed above.
+
+**To edit information in an existing chapter**
+
+1. Open the vignette corresponding to the chapter you wish to edit (see the _pkgdown.yml) 
+file for the chapter and its vignette path (href).
+2. Make your changes in the vignette.
+3. Run the `pkgdown::build_site()` function.
+
+**To add a new chapter**
+
+1. Create a Rmd file for the vignette via `usethis::use_vignette()` and make sure the 
+name of the vignette starts by "chapter", for example: 
+
+```
+usethis::use_vignette(name = "chapterSleep", 
+                      title = "10. How to analyse your sleep data in GGIR")
+```
+
+2. Open the [_pkgdown.yml](_pkgdown.yml) file and fill up the name and reference of the
+new chapter under menu. Make sure to follow the coding and structure of the rest of chapters.
+3. Run the `pkgdown::build_site()` function.
+
+**To remove a chapter**
+
+1. Remove the lines corresponding to the chapter in the [_pkgdown.yml](_pkgdown.yml) file
+in line 42 onwards.
+2. Optionally you may remove the Rmd file corresponding to the chapter, but only by doing the
+step 1, the chapter will not appear in the github.io website.
+3. Run the `pkgdown::build_site()` function.
+
+**To edit the name of a chapter**
+
+Chapter names are defined twice, in the [_pkgdown.yml](_pkgdown.yml) file and in the
+vignette file itself. You need to make sure both titles match as the first will be 
+used in the drop-down list in the github.io website and the other in the specific
+page for the chapter. 
+
+#### Adding the changes to the master branch
+
+The last step would be committing and pushing your changes to github and making a
+pull request as with any other contribution to the package. Note that, running the 
+`pkgdown::build_site()` function will edit the files within the docs folder, and 
+probably add some new files. This only applies when editing information from the 
+github.io website. It is important that these changes to the files in the
+docs folder are also part of the pull requests, as otherwise the website would not 
+be updated.
+
 ## New release
 
-GGIR follows the [release cycle process described in this document](RELEASE_CYCLE.md).
+GGIR follows the [release cycle process described in this document](RELEASE_CYCLE.md).
diff --git a/NEWS.md b/NEWS.md
@@ -25,6 +25,8 @@ relative to start and end of the most active time window as identified.  #905
 
 - Fix recently introduced bug where GGIR environment was not exported to cluster in GGIR part 1, 2, 3, and 5 #910
 
+- Add contributing guidelines for github.io documentation #923
+
 # CHANGES IN GGIR VERSION 2.10-3
 
 - Part 1: Fixed minor bug in ismovisens that failed when datadir started with "./" #897

diff --git a/docs/404.html b/docs/404.html
diff --git a/docs/CODE_OF_CONDUCT.html b/docs/CODE_OF_CONDUCT.html
diff --git a/docs/CONTRIBUTING.html b/docs/CONTRIBUTING.html
diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html
diff --git a/docs/RELEASE_CYCLE.html b/docs/RELEASE_CYCLE.html
diff --git a/docs/articles/CutPoints.html b/docs/articles/CutPoints.html