Contributing to easy.gems

Great to have you here 👋 and thank you very much for your interest in contributing to easy.gems 👍. We welcome contributions from anyone of any kind, e.g. notes about errors, requests for more articles or better descriptions, questions about specific examples, direct updates to articles or new articles, better illustrations and more.

This document should give you a little guide, how we try to organise these kinds of contributions. Our process of updating easy.gems is closely tied to workflows common to gitlab, so they might be familiar, but probably there’s something new to learn as well. In particular, we are using gitlab.dkrz.de for collaboration. If you don’t already have an DKRZ user account, you’ll have to create one to contribute.

We collect things which are not yet written out in the form of issues. These could be ideas, plans, requests, bug reports etc… all the things for which you don’t have an immediate solution at hand, want to discuss with someone or seek for others to do it 😁. Thus, if you would like to have some things improved, please have a look at our existing issues, where you might already find similar requests and can add some emphasis or additional input. If you don’t find anything related, please open a new one and describe what you like to see. Each issue opens something like a small chat forum for exchange about the requested topic. It’s also a place to collect required information or further plans if needed.

Changes to the easy.gems website happen via merge requests. A merge request is a bit similar to an issue, as it also opens up a small chat forum. However, it is always tied to a certain set of changes to the source code of easy.gems. As easy.gems technically is a static website, the source code consists of all the things which make up the site, that is the content, the layout and styles and the instructions how to generate the site. Changes to any of these will happen in a git branch (more on that later) and those changes will be reviewed and merged back into the main version of easy.gems using a merge request. Please have a look at our existing merge requests. If you see some open requests on topics you know a bit or two about, please help us out by Reviewing it.

If you want to add your own changes, there are two options: very small changes (e.g. spelling errors) can be made quickly by using the Edit this page button on each page. This will direct you to a little text editor where you can type your changes and which will lead you to the creation of a merge request. For anything larger, you’ll have to get a local copy of the git repository as described in Adding Content.

Reviewing

To review a merge request, one would usually go to the individual merge request page (you can check if there’s currently an open one, otherwise please have a look at existing Merged requests). On the Overview page, you’ll find the initial description of the merge request as well as the discussion. On the Changes page, you’ll find a diff-view of the files which actually have been changed. It’s a good idea to look through those changes first, such that you see which parts of the site have been touched and which haven’t. Generally, only those parts which are described on the Overview page should be touched by the changes.

Back on the Overview, there is a small panel which informs about some pipeline which may or may not have been executed for the merger request. Those pipelines are some scripts which are executed automatically for every merge request. The scripts include some checks and are building the easy.gems site itself. If the pipeline was successful, you should also see a button called View app right below the pipeline panel. This button sends you to a preview-version of easy.gems, which is built as if the merge request would have been merged already. That preview-version is a good place to get a visual impression of the merge request.

When reviewing a merge request, please check if the actual Changes correspond to the description in the Overview and check if the content of the changes looks good to you. Please note suggestions which you may find useful for this merge request, but please also try to keep the merge request on topic (i.e. what its title / description is about). If issues which extend beyond the scope of the merge request arise, please open a new issue and reference back to the originating merge request. This will help us to finalize merge requests quickly and not to loose time in overly long discussions.

Adding Content

New content is added using the git version control system. There are many good resources describing git in general, this document will only cover the basics. If you search for more information, maybe the git book or gitready are good starting points.

The starting point will be the source repository for this documentation at https://gitlab.dkrz.de/easy/gems/. If you haven’t done already, please go there and “request access”.

Once you have access, you can perform small edits on the files directly there (just as if you use the Edit this page button on an article page). For bigger changes, we recommend you clone the repository via SSH:

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

At this point, you have a fresh local copy of the source files of the easy.gems book on your computer. You can edit this copy as you wish and send these edits back to the main repository afterwards. To do so, you may want to create a new git branch at this point already (git checkout -b, see below), but you can also do this later. For some more specific hints about how to edit pages, please refer to the sections below.

To preview your edits, you need sphinx and some other dependencies:

python3 -m pip install -r requirements.txt

Further below, you can find some specific hints on adding content in our two mainly used formats reStructuredText and Jupyter Notebooks.

After doing your edits, you are ready to go and can build the book by running:

make html

You’ll find the index page at build/html/index.html, please open in in your favourite web browser. You can repeatedly edit the source files, run make html and refresh the web-page until you are happy with your change. Afterwards, it’s time to send your changes back to the main repository.

In order to do some automatic cleanup, we are using pre-commit. Please activate it for your local repository once before doing your first commit using:

pre-commit install

If you haven’t done so yet, please create a git branch (you’ll have to choose a name):

git checkout -b MY_CREATIVE_BRANCH_NAME

Afterwards, you’d be adding your changed files to the so called “staging area”, which marks them as to be committed:

git add [MY_CHANGED_FILES]

The next step is to actually commit your changes to your local clone of the repository. For each commit, you should come up with a descriptive message, explaining what you did. If it’s a short one, you can add the message on the command line using the -m option. If you want to explain more, just skip the message and git will open a text editor for you:

git commit -m 'my fancy changes'

Now, it’s time to do the actual upload of your branch (you’ll have to specify the same name as above):

git push -u origin MY_CREATIVE_BRANCH_NAME

Finally, please create a merge request for your branch, which will do some checks and build your new version in a “review environment” (after a few minutes, you’ll find a link to “View app” on the merge request page). This will give others the option to have a quick look at what you did, and if everything is fine, your changes will be merged into the current main branch and become publicly visible at https://easy.gems.dkrz.de/.

Adding jupyterlab/ipython notebooks

You can directly add ipython notebooks to the gitlab repository. They will be parsed by the nbsphinx plugin.

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

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

paired notebooks

pre-commit

Note

We are using jupytext paired notebooks within Easy Gems. Please follow the instructions below to create new paired notebooks.

We use paired notebooks, because we want

  • a plain-text notebook format to facilitate reviews and

  • we also need the output of each computed cell because we (currently) can’t simply re-run all the notebooks because they might require loading a lot of data

Jupytext can convert bidirectionally between structured ipynb files and (more-or-less) plaintext formats. It can also check if two files are synchronized. Jupytext is well-integrated into jupyter notebooks, so when working with already paired notebooks, you shouldn’t notice anything. When creating a new paired notebook, just create a “normal” notebook and use the Jupytext context menu to create a paired notebook in the formats ipynb and MySt Markdown. Alternatively you can create this pairing on the command line using:

jupytext --set-formats ipynb,myst your_notebook.ipynb

Before committing your modifications to the git repository, you’ll always have to ensure that the notebooks are synchronized. You can either do this manually by executing

jupytext --sync your_notebook.ipynb

But the preferred way would be to do this automatically using pre-commit, which will automatically suggest synchronizing your notebooks upon commit should it be needed (and we also use this on the server to verify that no one forgot to do this). To set up pre-commit for your local clone of the Easy Gems project, please run:

pre-commit install

once in your cloned repository. Afterwards, pre-commit will automatically check your notebooks whenever that might be required and will remind you if anything is missing.

Adding text articles

easy.gems uses reStructuredText (reST) as markup language for text articles. Please refer to the linked document for a general introduction into reST. Below are some further tricks for writing special content blocks:

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.