Skip to content
Snippets Groups Projects
Commit ec767cf6 authored by Andrew Coward's avatar Andrew Coward
Browse files

Correct a few typos in source/editguide.rst

parent 70f53be9
No related branches found
No related tags found
No related merge requests found
......@@ -9,7 +9,7 @@ Overview
========
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.
``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.
......@@ -20,10 +20,10 @@ These pages will:
* 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 rst 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.
There are plenty of on-line resources to help with this and the NEMO user-guide ``rst``
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.
.. _LocationGuide:
......@@ -35,21 +35,22 @@ Location of the source material
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 Workspaces`` group and one as
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
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 ``Sites``
only include the source material as a submodule reference to the ``User guide`` project
under ``NEMO Workspaces``. All developers are able to create issues and merge requests and
commit to branches of this project. 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 once an officer has updated the submodule reference
in the appropriate ``Sites`` project.
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 ``Sites``
project.
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,
......@@ -62,8 +63,8 @@ of this very section of the user guide.
Preparing to edit the guide
===========================
Preparation follows the same procedure as any development. I.e. create and issue and
linked merge request in the GUI for the ``NEMO Workspaces > Documentation > 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`_
.. _User guide: https://forge.nemo-ocean.eu/nemo/doc/guide
......@@ -158,7 +159,7 @@ easily obtained from alternatives or installed using pip:
conda install -c conda-forge sphinxcontrib-bibtex
python3 -m pip install sphinxext-remoteliteralinclude
As an example, these commands on a Macbook results in the following sphinx install:
As an example, these commands on a Macbook resulted in the following sphinx install:
.. code-block:: bash
......@@ -181,7 +182,7 @@ from the rst files is as simple as:
make html
from the top guide directory. A successfu build should look something like:
from the top guide directory. A successful build should look something like:
.. code-block:: bash
......@@ -248,7 +249,7 @@ After completing your edits and successfully previewing, push back the changes:
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.
changes approved and merged. Your role as developer is now complete (pending future updates).
.. _PublishGuide:
......@@ -282,7 +283,7 @@ The same procedure is required when updating the release version of the user gui
the additional recommendation that the commit message mentions which release this commit
is designed for (and make sure this matches ``versions`` as set in ``source/conf.py``):
Updating of the user guide is expected to occur much less frequently than updating of
Updating of the user guide is expected to occur much less often than updating of
the draft user guide.
.. code-block:: bash
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment