Repository Structure

A submission repository has a number of expected configuration files, content files and folders dependent on the authoring toolchain used, and if based on a template repository, will also contain GitHub Actions workflows.

Let’s review and get familiar with the various elements.

Toolchain specific elements¶

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
.
├── .github
│   └── workflows
│       └── deploy.yml
├── .gitignore
├── README.md
├── _toc.yml
├── article.md
├── data
│   ├── catalogoComunSV_1663233588717.csv
│   └── lapalma_ign.csv
├── environment.yml
├── images
│   ├── banner.png
│   ├── la-palma-eruption-2022-paper.png
│   ├── la-palma-map.png
│   ├── reservoirs.png
│   └── stations.png
├── myst.yml
├── notebooks
│   ├── data-screening.ipynb
│   ├── seismic-monitoring.md
│   └── visualization-figure-creation-seaborn.ipynb
└── references.bib

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
.
├── .github
│   └── workflows
│       └── publish.yml
├── .gitignore
├── .luarc.json
├── README.md
├── _extensions
│   └── quarto-journals
│       └── agu
│           ├── _extension.yml
│           ├── agu.lua
│           ├── agujournal2019.cls
│           ├── american-geophysical-union.csl
│           ├── partials
│           │   ├── _affiliations.tex
│           │   ├── _authors.tex
│           │   ├── _corresponding-author.tex
│           │   ├── before-body.tex
│           │   └── title.tex
│           └── trackchanges.sty
├── _quarto.yml
├── apt.txt
├── article.qmd
├── data
│   ├── catalogoComunSV_1663233588717.csv
│   └── lapalma_ign.csv
├── environment.yml
├── images
│   ├── la-palma-eruption-2022-paper.png
│   ├── la-palma-map.png
│   ├── reservoirs.png
│   └── stations.png
├── notebooks
│   ├── data-screening.ipynb
│   ├── seismic-monitoring-stations.qmd
│   └── visualization-figure-creation-seaborn.ipynb
├── postBuild
└── references.bib

Common elements¶

The following elements are present independent of the authoring toolchain used in your submission.

.github/workflows/*.yml

A GitHub Actions deployment workflow that will attempt to build your submission on each push to your main branch. Learn more in Pushing to GitHub. Normally, this file should not be changed.

environment.yml

The template repositories use a standard conda environment file for loading python dependencies. If you are using python and conda then we describe updating this file in Environment otherwise any set of Reproducible Execution Environment Specification (REES) files can be used to configure your repository as needed. REES ensures that any binderhub instance can provide a properly configured Jupyter server with required dependencies to reviewers and readers. (Note: the Quarto templates already include additional REES files apt.txt and postBuild),

data/

You may want to provide data files directly in your submission repository if they are needed for computations. These may be subsets or abstractions of the full data sets needed for generating figures, for example. Regardless, original data should be published separately in a suitable data repository. These and other data citations should be included in the reference section of the Notebook. For more on this topic, see Best Practices.

.gitignore

A standard git ignore file allowing you to exclude local files from your submission. This is useful if your scripts or notebooks generate additional temporary files when they are run, for example downloaded data files or temporary result files. Customize this file to fit your needs by adding ignore patters.

Content¶

The image below shows the sample content and toolchain specific configuration files included in the repository.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
.
├── _toc.yml
├── article.md
├── images
│   ├── banner.png
│   ├── la-palma-eruption-2022-paper.png
│   ├── la-palma-map.png
│   ├── reservoirs.png
│   └── stations.png
├── myst.yml
├── notebooks
│   ├── data-screening.ipynb
│   ├── seismic-monitoring.md
│   └── visualization-figure-creation-seaborn.ipynb
└── references.bib

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
.
├── .luarc.json
├── README.md
├── _quarto.yml
├── article.qmd
├── data
│ ├── catalogoComunSV_1663233588717.csv
│ └── lapalma_ign.csv
├── images
│ ├── la-palma-eruption-2022-paper.png
│ ├── la-palma-map.png
│ ├── reservoirs.png
│ └── stations.png
├── notebooks
│ ├── data-screening.ipynb
│ ├── seismic-monitoring-stations.qmd
│ └── visualization-figure-creation-seaborn.ipynb
├── postBuild
└── references.bib

With both toolchains:

references.bib

References are provided in standard bibtex in a single file at the root of the repository. If you intend to rename this file, refer to your authoring tool’s documentation.

images/, notebooks/

You are free to organize images, notebooks, scripts and other data files within the repository as needed and reference these as normal from markdown or ipynb files, or otherwise use them as supported by the authoring tool that you are using.

article.(md/qmd)

This markdown file at the root of the repository is the main manuscript that references and links to the other notebooks in the repository. The filename is not fixed, but if changed, the configuration files for the authoring tool should be updated appropriately.

Next Steps¶

Now that you are familiar with the contents of your repository, let’s look at the authoring environment available for each toolchain and understand how to work locally with your content.