How to contribute to easy.gems

Adding Content via git(lab)

You can find the source for this documentation at https://gitlab.dkrz.de/easy/gems/

To request (write) access go to https://gitlab.dkrz.de/easy/gems and click on “request access” at the top.

Once you have access, you can perform small edits on the files directly there. For bigger changes, we recommend you download the repository:

git clone git@gitlab.dkrz.de:easy/gems.git

QA

Q: How can I work with git, SSH-keys and gitlab.dkrz.de?

A: Once you have logged in on gitlab (same login/password as for mistral), you need to set up SSH key auth (follow the advice at https://gitlab.dkrz.de/-/profile/keys for generating ssh keys on your machine). You can register your key on gitlab (same link as above). After that you can run the download command from your local home over terminal.

To test your edits, you need sphinx:

cd gems
make html

QA

Q: How do I install sphinx for building the pages?

A: You need to install sphinx, an html builder and nbsphinx for importing jupyter notebooks. Please have a look at the official installation instructions for various options. If you are using conda, you can simply run

conda install sphinx
conda install -c conda-forge nbsphinx

You can find the index page at build/html/index.html

Finally, push the changes to gitlab:

git checkout -b MY_CREATIVE_BRANCH_NAME
git add [MY_CHANGED_FILES]
git commit -m 'my fancy changes'
git push -u origin MY_CREATIVE_BRANCH_NAME

After a minute or two, your changes will be visible at https://easy.gitlab-pages.dkrz.de/gems/

Finally send a merge request for your branch and we will merge things into the master.

Adding Math

:math:`\sum_{i=1}^n i^2`

.. math::
   \sum_{i=1}^n i^2

yields \(\sum_{i=1}^n i^2\)

\[\sum_{i=1}^n i^2\]

Adding code snippets

Use the following syntax:

.. code:: python

   print ("hello world")

To produce

print ("hello world")

Note that there needs to be an empty line before the .. code-block:: directive, and the code needs to be indented. Similarly many other languages are supported.

For inline code, you can use

:code:`sample code`

to produce sample code.

Adding jupyterlab/ipython notebooks

You can directly add ipython notebooks to the gitlab repository. They will be parsed by the nbsphinx plugin. Please make sure to have a Title and copyright information at the top of your notebook. We recommend an open source license such as the BSD-3-Clause-License.

../_images/ipynb-header-copyright.png

The raw notebook can be downloaded via the Page source link at the bottom of the page.