CONTRIBUTING.md

# Contributing {#contributing}

Contributions of all kinds are welcome.  By offering a contribution, you agree
to abide by our
[Code of Conduct](https://github.com/merely-useful/py-rse/blob/book/CODE_OF_CONDUCT.md)
and that your work may be made available under the terms of our
[license](https://github.com/merely-useful/py-rse/blob/book/LICENSE.md).

## Setting Up and Building the Book {-}

This book is written in [Bookdown](https://bookdown.org/).
To preview it on your computer,
run `make html` or `make pdf` on the command line
and then open `_book/index.html` or `_book/py-rse.pdf` respectively.
If you prefer working in the RStudio IDE:

1. Install R and RStudio.

1. Open `py-rse.Rproj` .

1. Install the dependencies by running:

    ```r
    install.packages("remotes")
    remotes::install_deps()
    ```

1. Build the website by using Ctrl-Shift-B.

Please note that Bookdown works best with [TinyTeX](https://yihui.name/tinytex/).
After installing it, you can run `make tex-packages` to install all the packages this book depends on.
You do _not_ need to do this if you are only building and previewing the HTML versions of the books.

## Adding Content {-}

The main development branch is `book` and the website is built on `gh-pages`.
To add content, create a new branch, make your changes, and then submit a PR.
Please only create a PR when you are ready for your change to be reviewed and merged in.
Please only edit `index.Rmd` in the root directory or the `.Rmd` files in the `chapters` directory.

-   The ID for each chapter and section heading is set by putting
    `{#some-label}` on the heading line. Please use the stem of the file's name in
    labels, i.e., start all labels for chapter `stuff.Rmd` with the word `stuff`.

-   Each chapter starts with a list of learning objectives and ends with a list
    of key points. These lists are kept in plain Markdown files in the
    `objectives` and `keypoints` folders respectively so that they can be
    included in both the chapters and the `objectives.Rmd` and `keypoints.Rmd`
    appendices.

-   Please use `[text][label]` to refer to links and put the URL itself in the
    `links.md` file to ensure consistency between chapters.

-   Please use [diagrams.net](https://www.diagrams.net/) to draw diagrams. Save
    the source as `figures/stem/stem.drawio` and export drawings as PDF, PNG,
    and SVG.

-   Since LaTeX doesn't understand SVG, include diagrams as follows:
    -   Create an R code block with the header `{r stem-label, echo=FALSE, fig.cap="Some Caption"}`.
        This gives the figure the ID `fig:stem-label` because Bookdown
        automatically puts `fig:` in front of figure labels.
    -   Use `insert_graphic("figures/stem/filename.ext")` in the code block to
        include the image.  If you are using a `.pdf` image, make sure that you
        have the same file but as a `.svg` as well.

-   Use `@Name123` or `[@Name123]` to refer to bibliography entries
    (the latter puts the citation in braces).
    These entries must exist in the `book.bib` file.
    To cite multiple entries in braces,
    separate the keys by semicolons, e.g., `[@Name123; @Name456; @Name789]`.
    
-   Use `\@ref(label)` with parentheses (not curly braces) to refer to labels
    for sections and figures. Note that this only inserts the section number,
    not the words `Chapter`, `Appendix`, `Section`, or `Figure`---you must add
    that yourself.

-   Glossary entries are in `glossary/glossary.md`, which is generated by
    combining entries from the
    [glosario](https://github.com/carpentries/glosario/) project with custom
    entries from `glossary/glossary.yml`.  To refer to a glossary entry, put
    `\gref{some words}{glossary_key}` in the `.Rmd` file.

-   We use Simplified English rather than Traditional English (i.e., American
    rather than British spelling and grammar). We also use first person plural
    ("we") in exposition, but speak directly to the reader ("you") when giving
    directions in exercises.
    
-   Code blocks with syntax highlighting can be created using the keywords
    `python`, `bash`, `diff`, `markdown` or `makefile`.
    The keyword `text` isfor code blocks without syntax highlighting and
    is mainly used to display the output from code executed in a code block. 

## Coding {-}

We follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) for Python,
breaking its rules only in order to lay things out neatly on the printed page.
Specific conventions include:

-   `variable_name`, `function_name`, and `method_name` (snake case).

-   Do not use empty parentheses to indicate a function, as this makes it hard to
    distinguish a function name from a call with no arguments.

-   `file_name` and `folder_name/` (underscores instead of hyphens underscores,
    trailing slash for directories consistent with `ls -F`).

-   `'string'` (single quotes) rather than `"string"` (double quotes).

## Package Installation {-}

GitHub Actions needs to know what packages to install to build the website. To
add a Python package dependency, include the package name as a new line in the
`requirements.txt` file.