How To Contribute

This online book is developed using MyST, which renders MyST markdown and Jupyter notebooks into a web accessible format. Therefore the way to create content is to either compose a markdown document (.md) or a Jupyter notebook (.ipynb) file and then add it to the myst.yml file.

Creating MyST markdown¶

MyST markdown is more extensible than Markdown and is focused on scientific writing. For more information see MyST.

Creating Jupyter Notebooks¶

Jupyter notebooks allow detailed text along with executable code. This provides students with a lot of information and interactivity. For more information on Jupyter notebooks see Jupyter Documentation.

Adding Material¶

Once you’ve created material you’ll want to add it to the rendered material. To do this open up the myst.yml found in the repository and add your file or folder to the table of contents toc part. Indentation is important. You can see from the example below the pattern is a section is title: section name then children which will include various types of files or other. Then a sub-section will have a similar patter, just with a further indentation.

version: 1
project:
  title: Summer of Applied Geophysical Experience Field Camp
  description: Documentation and working examples for open-source Python packages to work with magnetoteluric data.
  keywords: [magnetotellurics]
  authors: SAGE 
  license: CC BY 4.0
  thumbnail: ./images/SAGE_Logo.png
  github: https://github.com/SAGE-Geophysical-Field-Camp/sage-geophysics.github.io
  # To autogenerate a Table of Contents, run "myst init --write-toc"
  toc:
    # Auto-generated by `myst init --write-toc`
    - file: README.md
    - title: Section
      children:
      - file: ./path_to_new_file/new_markdown.md
      - file: ./path_to_new_file/new_notebook.ipynb
    - title: New Section
      children:
      - title: New Sub Section
        children:
          - file: ./path_to_new_file/new_markdown.md
          - file: ./path_to_new_file/new_notebook.ipynb

Contributing¶

All markdown and Jupyter notebooks are stored in the SAGE-Geophysical-Field-Camp Git repository. This helps keep the files organized as well as version controlled. Moreover, upon a commit is pushed a Git Action will be triggered to render the website https://sage-geophysical-field-camp.github.io.

If you are new to git checkout Git documentation and GitHub documentation.

Members¶

If you are a member you have access to commit, push, and pull using git.

Non-members¶

If you are not a member then you can fork the repository to your own GitHub account, make changes, and then create a pull request back into the main branch of the repository.

Important Steps¶

Some important steps to keep in mind:

• Always pull before push to make sure you are using the latest version of the repository
• Be cautious if you are committing large amounts of information. Suggest using a pull request for big changes or large updates to the material.
• Commit often when making changes, this not only keeps a record of changes, but if something breaks or you want to revert back to an older version its much easier.

Pull Request¶

A pull request is request to add code to a certain branch of the original repository, in this case it will be the main branch. In the pull request (PR), be sure to add information about what was changed or added so that maintainers know what they are merging. For example,

• If you are adding exectuble code, was a test added to make sure the code runs properly?
• Did you add documentation, information material, or other?
• How will the update benefit the material?

¶