Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
199 lines (125 loc) · 5.89 KB

CONTRIBUTING.md

File metadata and controls

199 lines (125 loc) · 5.89 KB

Contributing

View locally

This website is created using Quarto and hosted on GitHub pages. You can view the site locally. With quarto installed, you will need to:

1. Build the python environment

conda env create --file environment.yaml
conda activate des-rap-book

2. Build the R environment

renv::init()
renv::restore()

3. Create the book.

quarto render

Common reticulate error and solution

When rendering a Quarto document containing executable Python code with reticulate, configuration errors can occur if R is not using the same Python as your conda/mamba environment.

Whilst you can use reticulate::use_condaenv() on each page, this caused errors for our GitHub action - and anyway, a more robust approach is to configure which Python interpreter reticulate should use.

  1. Identify the Python binary for your environment:
conda env list

For example, if you environment is at /home/amy/mambaforge/envs/des-rap-book, the Python binary will typically be /home/amy/mambaforge/envs/des-rap-book/bin/python.

  1. Create a .Renviron file. This is not tracked by Git and is user-specific. In it, specify your Python binary and conda/mamba executable. For example:
RETICULATE_PYTHON=/home/amy/mambaforge/envs/des-rap-book/bin/python
RETICULATE_CONDA=/home/amy/mambaforge/bin/conda

Linting

To lint active Python and R code:

bash lint.sh

Note: inactive code (i.e. code that does not get run when building the book) will not be linted - though the R linter will enforce a terminal newline at the end of each .qmd file.


Pre-commit

To activate the pre-commit hook...

  1. Make the bash script executable - from command line, run:
chmod +x .pre-commit-hooks/check-no-quarto-r-include.sh
  1. Run the following from your python environment on the command line:
pre-commit install

Contributors

If your name or contributions are missing from the README, or if you contributed in ways not captured by the current role emojis, please create an issue and use:

@all-contributors please add @githubuser for ...

Then list appropriate contribution types from allcontributors.org/docs/en/emoji-key (e.g., code, review, doc, content, bug, ideas, infra).

Alternatively, you can update it from the command line. This may be preferable, as the bot will create GitHub issues that email people when they are added.

You'll need to install the All-Contributors CLI tool:

npm i -D all-contributors-cli

You can then run the following and select/enter relevant information when prompted:

npx all-contributors

If you want to remove specific contributions or people, edit the .all-contributorsrc file then run the following to regenerate the table in README.md. (Don't edit README.md, as it is just generated based on .all-contributorsrc).

npx all-contributors generate

Docker

The GitHub action to build the website uses docker, as this avoids needing to install all the required Python and R packages and system dependencies with every deployment (unless there are environment changes).

If you wish to build the docker image locally to test it out, run this command from the project directory:

sudo docker build -t desrapbookdocker .

To view your available images, run:

sudo docker images

Open the container interactively:

sudo docker run -it desrapbookdocker /bin/bash

Restore R environment:

Rscript -e "renv::restore()"

Edit the conda location in .Renviron (if present) to RETICULATE_CONDA=/opt/conda/bin/conda:

apt-get update && apt-get install nano
nano .Renviron

Build the website:

quarto render

To close the container: Ctrl+P then Ctrl+Q.

To delete the image:

sudo docker image rm -f desrapbookdocker

Accessibility

This site uses W3C's Web Accessibility Initiative (WAI) Easy Checks as a lightweight accessibility framework. Please see this GitHub issue for a record of which checks are currently met and any known limitations.

Quarto's supported accessibility checker axe is not used because it is difficult to read, and it mostly flagged things that cannot be changed (i.e., Quarto defaults and built-ins). As such, other approaches are used.

lint_alt_text.py

A Python script is provided which checks for alt text. It supports patterns:

  • ![alt-text](fig.png)\ (backslash required for it to use caption as alt-text too).
  • <img src="fig.png" fig-alt="alt-text">
  • ![](fig.png){fig-alt="alt-text"}

To run the script:

python lint_alt_text.py

This is configured to run via GitHub actions - see .github/workflows/lint_alt_text.yml.

Findability checks

To support the FAIR principles for training materials, we keep a light-weight record of how easy it is for learners to discover the DES RAP Book via web search and chatbots. This helps us see whether changes to the site or metadata (for example, adding structured metadata or registering in training registries) actually improve real-world discoverability.

If you’d like to help with this, please see findability_checks.md. That file explains:

  • Which example queries to use.
  • Where to run them (e.g. search engines, chatbots).
  • How to record the results in the simple log.

You are welcome to run these checks occasionally, for example:

  • After major changes to the site or its metadata.
  • After registering the resource in a new training registry.
  • Or just periodically (e.g. once or twice a year) as part of general maintenance.

Even occasional contributions to the findability log are helpful for tracking whether learners can still easily find the resource over time.