Skip to content
GitLab
Explore
Sign in
Register
Primary navigation
Search or go to…
Project
User guide
Manage
Activity
Members
Labels
Plan
Issues
2
Issue boards
Milestones
Iterations
Requirements
External wiki
Code
Merge requests
0
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Locked files
Build
Pipelines
Jobs
Pipeline schedules
Test cases
Artifacts
Deploy
Releases
Model registry
Analyze
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Terms and privacy
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
NEMO Workspace
Documentation
User guide
Commits
ec767cf6
Commit
ec767cf6
authored
1 year ago
by
Andrew Coward
Browse files
Options
Downloads
Patches
Plain Diff
Correct a few typos in source/editguide.rst
parent
70f53be9
No related branches found
No related tags found
No related merge requests found
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
source/editguide.rst
+20
-19
20 additions, 19 deletions
source/editguide.rst
with
20 additions
and
19 deletions
source/editguide.rst
+
20
−
19
View file @
ec767cf6
...
@@ -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
``
S
phinx`` package from ReStructured Text (rst) files using the ``Read The Docs`` theme.
``
s
phinx`` 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 Workspace
s
`` 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
M
aintainers (i.e. NEMO officers) can
projects in the ``Sites`` group. For security, only
m
aintainers (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 an
d
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 Workspace
s
> 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 result
s
in the following sphinx install:
As an example, these commands on a Macbook result
ed
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 successfu
l
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
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment