Making changes to the User Guide
The NEMO User guide is a collection of html web-pages that are constructed via the python
sphinx package from ReStructured Text (rst) files using the
Read The Docs theme.
This part of the guide is for developers who wish to edit or add to the guide and for
maintainers who wish to make those changes live.
These pages will:
Explain where the source material is located within the GitLab repository
Describe how developers can clone the material, edit and build locally.
Explain how live html versions can be updated by maintainers (officers)
These pages will not discuss the ReStructured Text syntaxes or directives themselves.
There are plenty of on-line resources to help with this and the NEMO user-guide
files themselves already contains examples of most of the constructs you are likely to
need. Simply find a close match to the type of layout you are after, cut-and-paste the
section and change the content.
The source material for the user guide appears to be located in multiple locations in the
NEMO GitLab repository. Two
User guide projects are shown in the systematic above. One
as a project in the
Documentation subgroup of the
NEMO Workspace group and one as
a project in the
Sites group. There is also a
Draft User guide project under
Sites, but more about that later. The apparent duplication is intentional and serves
to separate the files that any developer can edit from the copies on the publically
accessible Web server.
The public pages are deployed to a static website by a GitLab Pages server that runs on
projects in the
Sites group. For security, only maintainers (i.e. NEMO officers) can
create and edit projects in the
Sites group. However, the projects under
only include the source material as a submodule reference to the
NEMO Workspace >
Documentation > User guide project. All developers are able to create issues and merge
requests and commit to branches of
NEMO Workspace > Documentation > User guide.
Hence, all developers are able to contribute to the user guide. Maintainers can review
and accept merge requests like any other development. Any merged material will only become
live html once an officer has updated the submodule reference in the appropriate
This may appear confusing but is relatively simple in practise. The next few sections illustrate the steps needed to create an issue, merge request and branch, make a change, review the change locally, push changes back, have the changes merged and ultimately have the html versions created and deployed. The example used for illustration is the creation of this very section of the user guide.
Preparation follows the same procedure as any development. I.e. create an issue and
linked merge request in the GUI for the
NEMO Workspace > Documentation > User guide
project at User guide
The following images illustrate the process for the changes that created this section of the guide:
Create a new issue (use the
Include a brief description
Create a linked merge request and branch
With the merge request and new branch in place, the project can be cloned to your local machine for editing:
git clone --recurse-submodules firstname.lastname@example.org:nemo/doc/guide.git cd guide git branch -a git switch 10-add-developers-guide-section-on-how-to-make-changes-to-the-user-guide
Note the namelists and gallery subdirectories are submodules. The contents of these are unlikely to change often (at least any parts actually used in the user-guide) but, if you need to update the references then descend into the appropriate directory and issue the update command; e.g.:
cd namelists git submodule update --init --force --remote git add namelists
Otherwise, just edit or add to the
source directory content as required. For example:
vi source/index.rst vi source/editguide.rst cp ~/Pictures/guide_*.png source/_static/ cp ~/Pictures/repo_layout.png source/_static/ git add source/_static/guide_*.png source/_static/repo_layout.png git add source/index.rst source/editguide.rst
The ability to preview your changes (and hence check for build-time errors) is an essential requirement of the development process. The next section explains how to set up and use a suitable environment.
To build and preview locally will require:
A python environment with
sphinxand a few
A browser with access to the local filesystem
Both requirements are easily satisfied on most Unix-based operating systems.
The Sphinx installation page lists many ways of installing
Perhaps the easiest being via
conda install sphinx
The required extensions are not always available from the default conda server but can be easily obtained from alternatives or installed using pip:
conda install sphinx_rtd_theme conda install -c conda-forge sphinxcontrib-bibtex python3 -m pip install sphinxext-remoteliteralinclude
As an example, these commands on a Macbook resulted in the following sphinx install:
conda list | grep sphinx sphinx 5.0.2 py37hecd8cb5_0 sphinx_rtd_theme 0.4.3 pyhd3eb1b0_0 sphinxcontrib-applehelp 1.0.2 pyhd3eb1b0_0 sphinxcontrib-bibtex 2.5.0 pyhd8ed1ab_0 conda-forge sphinxcontrib-devhelp 1.0.2 pyhd3eb1b0_0 sphinxcontrib-htmlhelp 2.0.0 pyhd3eb1b0_0 sphinxcontrib-jsmath 1.0.1 pyhd3eb1b0_0 sphinxcontrib-qthelp 1.0.3 pyhd3eb1b0_0 sphinxcontrib-serializinghtml 1.1.5 pyhd3eb1b0_0 sphinxext-remoteliteralinclude 0.4.0 pypi_0 pypi
With a similar and correctly configured sphinx installation, building the html files from the rst files is as simple as:
from the top guide directory. A successful build should look something like:
make html sphinx-build -b html -d build/doctrees source build/html Running Sphinx v5.0.2 loading pickled environment... checking bibtex cache... up to date done building [mo]: targets for 0 po files that are out of date building [html]: targets for 0 source files that are out of date updating environment: [config changed ('extlinks')] 18 added, 1 changed, 0 removed reading sources... [100%] zooms looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] zooms generating indices... genindex done writing additional pages... search done copying images... [100%] _static/agrif_sponge.png copying static files... done copying extra files... done dumping search index in English (code: en)... done dumping object inventory... done build succeeded. The HTML pages are in build/html. Build finished. The HTML pages are in build/html.
The results can be previewed by opening the
build/html/index.html file in
your local browser. In my case this is:
The rendered page may look slightly different to the exact same version eventually built on the NEMO GitLab server. Compare, for example the two images of the landing page below. The html files are identical but the left-hand image is read from the local disk; the right-hand image is as the live user guide is displayed - in the same browser! Given this, local previewing should be used to check content and functionality without too much effort on fine tuning of precise layout.
After completing your edits and successfully previewing, push back the changes:
git add source/_static/guide_*.png source/_static/repo_layout.png git add source/_static/landing_views.png git add source/index.rst source/editguide.rst git commit -m'Added section on how to edit the user-guide. Successfully built and previewed locally' git push origin
In the GUI, go to the merge request page and
mark as ready. Contact the reviewer and have the
changes approved and merged. Your role as developer is now complete (pending future updates).
Once the new material has been merged, a maintainer can chose to update the live pages
by updating the submodule link in one of the
Sites projects. In most cases this
will be the
Draft User guide project since the
User guide project should only
change when a new code is released. The act of pushing the change back to the GitLab
server will trigger a pipeline that builds and deploys the html files:
git clone email@example.com:sites/draft-guide cd draft-guide git submodule update --init --force --remote git add guide git commit -m "update of submodule link" git push origin
Once both stages (test and deploy) of the pipeline have successfully completed, the new html pages will be available at https://sites.nemo-ocean.io/draft-guide/
The same procedure is required when updating the release version of the user guide, with
the additional recommendation that the commit message mentions which release this commit
is designed for (and make sure this matches
versions as set in
Updating of the user guide is expected to occur much less often than updating of the draft user guide.
git clone firstname.lastname@example.org:sites/user-guide cd user-guide git submodule update --init --force --remote git add guide git commit -m "update of submodule link for release X.X.X" git push origin
Once both stages (test and deploy) of the pipeline have successfully completed, the new html pages will be available at https://sites.nemo-ocean.io/user-guide/