WORK IN PROGRESS
This repository holds the source files for the AIMS Knowledge Systems eReefs tutorials hosted at https://bfordaims.github.io/ereefs-tutorials/.
Currently, a few basic tutorials are available for the languages R
and python
. In time we hope to add a wider range of tutorials, including for more advanced concepts. If you wish to see a tutorial on a specific topic you can add a request using the Github Issues feature, though please note that the development of subsequent tutorials is dependent on the time availability of the small number of contributing AIMS staff.
This is a static Quarto website hosted by Github Pages.
Webpages can be edited and added via the Github repository. To do this we must clone the repository, make changes to the relevant Quarto (.qmd
) documents, or add new Quarto documents to add new webpages, render the amended website on a local machine (using Quarto), and then push the changes to the repository.
This process can be changed by using Github Actions to render the Quarto website, though at present local rendering is sufficient.
To successfully render the website you will need the following:
-
A Github account with permissions to push to the ereefs-tutorials repository
-
The R packages and Python modules used within the scripts you are trying to render
- R packages are installed from an R console with the command
install.packages("<package_name>")
for packages hosted on CRAN; orremotes::install_github("<Github username>/<repo name>")
to install packages hosted in a Github repository. - Python modules are installed from a python console with the command
pip/conda/mamba install <module name>
(depending on the python package manager installed on your machine)
- R packages are installed from an R console with the command
- git
- An IDE such as R Studio or Visual Studio Code (with the R, Python, and Quarto extensions)
From the command line:
git clone <repo url>
Edit existing tutorials by editing the corresponding tutorials/<language>/<tutorial-name>/<tutorial_name>.qmd
file.
Create a new tutorial by creating a new folder in the corresponding tutorials/<language>
folder; name it with the tutorial name; and create a <tutorial_name>.qmd
file within the folder
Edits to the YAML or CSS files require you to render the entire website to implement the changes. You can do this with from the command line with
quarto preview <path to "ereefs-tutorials" folder> --render all --no-browser --no-watch-inputs
or by using the respective IDE controls (ctrl+shft+p > Quarto: Render Project
in VS Code).
Edits to a single .qmd
file can be rendered from the command line with
quarto preview <path to file> --no-browser --no-watch-inputs
or by using the respective IDE controls (ctrl+shft+p > Quarto: Render
in VS Code).
All website files are contained in the git repository ereefs-tutorials
. This includes:
-
📁
tutorials
contains the tutorial source files-
📁
r
andpython
sort the source files by language.- 📁
<tutorial-name>
contain the files associated with a specific tutorial, including the main tutorial file 📄<tutorial_name>.qmd
as well as other associated data, images, etc.
- 📁
-
-
📁
images
contains images for general use (e.g. the eReefs logo) -
📁
docs
contains the rendered website files - do not edit these file directly, they are updated automatically by Quarto upon rendering the website source files. -
📁
_extensions
contains Quarto extensions which extend Quarto's functionality (e.g. we use the fontawesome extension to include icons in virtually any of the website's text); do not edit. -
📁
_freeze
corresponds to the freeze execution option. This controls which code chunks are rendered. With freeze set to auto, the code output is reproduced only when the source code changes. This folder holds the cache-like items needed for this option. -
📁
.quarto
contains files used by Quarto behind the scenes - knowledge of these files is not needed; do not edit. -
📄
index.qmd
the website homepage source file. All other webpages must be linked to, either directly or derivatively, from the home page (or else will not be reachable). -
📄
_quarto.yml
is used to set global YAML settings (including theming and navigation). -
📄
style.css
is a global CSS style sheet applied to all webpages (sourced from the YAML file). -
📄
theme_changes_<light/dark>.scss
alter the light and dark website themes (e.g. the link color was changed from the default green to blue) -
📄
README.md
the documentation file for the website (displayed on the repository home page on Github).
ImportError: DLL load failed: The specified module could not be found.
when rendering a python tutorial. Try the solutions here (downloading Microsoft Visual C++ worked for me).
-
Tutorials should be self-contained in 📁
tutorials/<tutorial language>/<tutorial-name>
with a single 📄<tutorial_name>.qmd
file and all other files required to run the tutorial (e.g. images, data). This allows people to download the individual folders to run specific tutorials on their own machine. -
Any file which does not pertain to a specific tutorial should be placed in either:
- 📁
~
style or theme files (e.g. YAML, CSS, SCSS) belong in the home folder - 📁
~/images
for images - 📁
~/resources
not yet created; would house any file which is not an image or style/theme file and which does not pertain to a specific tutorial
- 📁
-
Pay attention to the folder structure and file naming conventions used already. It would be nice to keep these consistent.
-
Push changes to the repository only after the entire website has rendered successfully (rather than just the specific tutorial) and you have tested it in a browser window (including a check that links work as desired). This will ensure the website will not break the next time it is rendered as a whole.
-
Check file links are correct.
-
Update this
README.md
documentation file as you go, including the resolution of any errors/issues you have encountered.