Skip to content

Latest commit

 

History

History
113 lines (84 loc) · 5.04 KB

CONTRIBUTING.md

File metadata and controls

113 lines (84 loc) · 5.04 KB
Raw

Contributing {#contributing}

Contributions of all kinds are welcome. By offering a contribution, you agree to abide by our Code of Conduct and that your work may be made available under the terms of our license.

Setting Up and Building the Book {-}

This book is written in Bookdown. 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.

  2. Open py-rse.Rproj .

  3. Install the dependencies by running:

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

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

Please note that Bookdown works best with 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 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 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 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.