Contributing

If you plan to do anything beyond fixing a typo, the best thing you can do is to open an issue and discuss changes before you spend a lot of time doing them.

If you want to contribute, some general advice is:

• Keep the changes small in scope. If the overall change is larger, make a sequence of small pull requests.

• The edits cannot include exact code that is under another license (i.e., don’t just copy/paste from R sources, etc.)

• Stick to using python for computations.
  

• Don’t update software versions unless you have to. If you need to update or add something, use Pipenv (described below) to codify the software requirements.

A merged PR is considered a donation of your work to this project. You are still bound by the conditions of the license, meaning that you are not considered an author, copyright holder, or owner of the content once it has been merged in.

You will mostly work with the *.qmd files in the chapters directory.

Here is a list of the elements in the repo:

├── _book                       # Created by quarto
├── _cache                      # Location of cached chunks  
├── _freeze                     # Created by quarto
├── _quarto.yml                 # configuration file
├── chapters                    # qmd content files
├── data                        # data files
├── figures                     # Location for created image files 
── includes                     # tex, bib, and html files to include
├── index.qmd                   # Initial quarto file
├── license.*                   # License information
├── Pipfile                     # basic environment specification
└── Pipfile.lock                # full environment specification

Software

Quarto

Quarto is an open-source scientific and technical publishing system. Quarto version 1.4.538 is used to compile the website.

python and Pipenv

Python 3.11.7 is what we are currently using. There are several IDEs that you can use. We’ve used VSCode.

I’ve set this up with Pipenv as an environment manager, but may switch.

Install pipenv if you don’t already have it. From the project top-level folder, run from a command line pipenv install. This may take some time, as it creates and populates an environment with all the required packages.

Building the site

From your pipenv (e.g. by starting in the root folder and running pipenv shell), run quarto render. This should run all the python snippets (using the pipenv python), caching some of the results, and render the output into /docs for you to preview. (For now, the github pages are also served directly from /docs, but eventually we will probably set up github actions to generate the docs on PR merges, at which point the local copy will be added to .gitignore and just for your preview.)