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 ...@@ -9,7 +9,7 @@ Overview
======== ========
The NEMO User guide is a collection of html web-pages that are constructed via the python 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 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. maintainers who wish to make those changes live.
...@@ -20,10 +20,10 @@ These pages will: ...@@ -20,10 +20,10 @@ These pages will:
* Explain how live html versions can be updated by maintainers (officers) * Explain how live html versions can be updated by maintainers (officers)
These pages will not discuss the ReStructured Text syntaxes or directives themselves. 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 There are plenty of on-line resources to help with this and the NEMO user-guide ``rst``
themselves already contains examples of most of the constructs you are likely to need. files themselves already contains examples of most of the constructs you are likely to
Simply find a close match to the type of layout you are after, cut-and-paste the section need. Simply find a close match to the type of layout you are after, cut-and-paste the
and change the content. section and change the content.
.. _LocationGuide: .. _LocationGuide:
...@@ -35,21 +35,22 @@ Location of the source material ...@@ -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 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 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 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 ``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 to separate the files that any developer can edit from the copies on the publically
accessible Web server. accessible Web server.
The public pages are deployed to a static website by a GitLab Pages server that runs on 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`` 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 only include the source material as a submodule reference to the ``NEMO Workspace >
under ``NEMO Workspaces``. All developers are able to create issues and merge requests and Documentation > User guide`` project. All developers are able to create issues and merge
commit to branches of this project. Hence, all developers are able to contribute to the requests and commit to branches of ``NEMO Workspace > Documentation > User guide``.
user guide. Maintainers can review and accept merge requests like any other development. Any Hence, all developers are able to contribute to the user guide. Maintainers can review
merged material will only become live once an officer has updated the submodule reference and accept merge requests like any other development. Any merged material will only become
in the appropriate ``Sites`` project. 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 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, 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. ...@@ -62,8 +63,8 @@ of this very section of the user guide.
Preparing to edit the guide Preparing to edit the guide
=========================== ===========================
Preparation follows the same procedure as any development. I.e. create and issue and Preparation follows the same procedure as any development. I.e. create an issue and
linked merge request in the GUI for the ``NEMO Workspaces > Documentation > User guide`` linked merge request in the GUI for the ``NEMO Workspace > Documentation > User guide``
project at `User guide`_ project at `User guide`_
.. _User guide: https://forge.nemo-ocean.eu/nemo/doc/guide .. _User guide: https://forge.nemo-ocean.eu/nemo/doc/guide
...@@ -158,7 +159,7 @@ easily obtained from alternatives or installed using pip: ...@@ -158,7 +159,7 @@ easily obtained from alternatives or installed using pip:
conda install -c conda-forge sphinxcontrib-bibtex conda install -c conda-forge sphinxcontrib-bibtex
python3 -m pip install sphinxext-remoteliteralinclude 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 .. code-block:: bash
...@@ -181,7 +182,7 @@ from the rst files is as simple as: ...@@ -181,7 +182,7 @@ from the rst files is as simple as:
make html 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 .. code-block:: bash
...@@ -248,7 +249,7 @@ After completing your edits and successfully previewing, push back the changes: ...@@ -248,7 +249,7 @@ After completing your edits and successfully previewing, push back the changes:
git push origin git push origin
In the GUI, go to the merge request page and ``mark as ready``. Contact the reviewer and have the 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: .. _PublishGuide:
...@@ -282,7 +283,7 @@ The same procedure is required when updating the release version of the user gui ...@@ -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 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``): 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. the draft user guide.
.. code-block:: bash .. 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