CONTRIBUTE_HOWTO

## Testing: HOW-TO

For automated testing, we use the `testthat` package. The basic testing unit is an *expectation*; 
a given computation has an expected result. A *test* is a group of related expectations, testing a 
single function or a single feature of a function. Finally, similar tests are grouped into a *file*, 
an `R` script; these files are located in the directory `tests/testthat`.

Expectations can assess a variety of results: equality, whether an object is of the correct class, 
if an output leads to a desired error or warning, etc.

For examples on how to design tests, see the directory `tests/testthat`. For more information, see 
Hadley Wickham's book on [*R packages*](http://r-pkgs.had.co.nz/tests.html) or his 
[article in the R journal](https://journal.r-project.org/archive/2011-1/RJournal_2011-1_Wickham.pdf).

Once new tests have been written, the whole test suite can be run locally using `devtools::test()`. 
Alternatively, the tests will be run on Travis CI every time a set of commits is pushed to GitHub.

Finally, we track code coverage using Jim Hester's package [covr](https://cran.r-project.org/package=covr), 
which represent the proportion of code lines that are run during some test. Locally, this can measured using 
the function `covr::package_coverage()`. And again it is run after a successful Travis check, and the results 
are uploaded to <codecov.io>; this allows us to keep track of code coverage via the badge at the top of the 
README file.

## Mkdocs: HOW-TO

This explains how to run the mkdocs. But first you need to install `mkdocs` and the third-party theme `material`.

```
pip install mkdocs
pip install mkdocs-material
```

1. Create a .Rmd in the docs folder. The .Rmd should have this at the top:

---
title: "data"
author: "Sahir"
date: "January 22, 2017"
output:
  md_document:
    variant: markdown
---

See http://rmarkdown.rstudio.com/markdown_document_format.html for different variants

For .Rmd documents with LaTeX in it (e.g. simulations.Rmd), I used
---
output:
  md_document:
    variant: markdown
---

For everything else I used
---
output:
  md_document:
    variant: markdown_github
---

2. click on knit. this will make an .md document in the docs/ folder

3. Add the name of the page and the .md document to mkdocs.yml (which is located in the root folder)

To (re)generate the site, run the following command from the root folder (the one that has the YAML file for the site):

```
mkdocs build
mkdocs gh-deploy
```

4. For mathjax:

first make sure you have root permissions on the python folder:

```
which python
python --version
sudo chown -R $USER /usr/local/lib/python3.5
```

then install python markdown math extension (see http://stackoverflow.com/questions/27882261/mkdocs-and-mathjax):

```
pip install https://github.com/mitya57/python-markdown-math/archive/master.zip
```

add the folowing to the YAML file

```
extra_javascript:
    - http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML

markdown_extensions:
    - mdx_math
```

### Further comments

    - used `knitr::kable(format = "html")` for tables, but still had to manually remove backslashes on underscores in the .md file

    - also had to manually remove backslahes on exponents in the .md file