New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 10279 for NEMO/trunk/doc/rst/source – NEMO

Ignore:
Timestamp:
2018-11-07T12:04:15+01:00 (5 years ago)
Author:
nicolasmartin
Message:

Various improvments for quick start guide

  • implementation of Rtd theme (Read the Docs) with custom layout and style file
  • add reviewed BibTeX entries for NEMO references with DOI (manuals, guide, development strategy)
  • enhancement of bibliography management and configuration file for guide building
  • standardisation of headings markup
  • numerous edits
Location:
NEMO/trunk/doc/rst/source
Files:
3 added
1 deleted
5 edited
4 moved

Legend:

Unmodified
Added
Removed

  • NEMO/trunk/doc/rst/source/NEMO_guide.rst

    r10201 r10279  
    1 .. NEMO documentation master file, created by 
    2    sphinx-quickstart on Tue Oct  9 18:14:01 2018. 
    3    You can adapt this file completely to your liking, but it should at least 
    4    contain the root `toctree` directive. 
    5  
    61################# 
    72Quick Start Guide 
    … …  
    94 
    105.. 
    11    A hidden .global.rst should be included in every subfiles with `include` directive 
    12    It contains a list of common URL links  
    13       
    14 .. include:: .global.rst 
    15  
    16 .. include:: readme.rst 
    17  
    18 Summary 
    19 ======= 
    20  
    21 .. toctree:: 
    22    :maxdepth: 1 
    23    :titlesonly: 
    24  
    25    release_notes.rst 
    26    install.rst 
    27    reference_configurations.rst 
    28    test_cases.rst 
    29    setup_configuration.rst 
    30    interfacing_options.rst 
    31    definitions.rst 
    32  
    33 .. 
    34    For headings markup, this convention is recommended from Python’s Style Guide 
     6   For headings markup, this convention is recommended from Python’s Style Guide 
    357   # with overline, for parts 
    368   * with overline, for chapters 
    … …  
    4012   ", for paragraphs 
    4113 
    42 .. 
    43    Indices and tables 
    44    ================== 
    45    * :ref:`genindex` 
    46    * :ref:`modindex` 
    47    * :ref:`search` 
     14   'global.rst' contains a list of common directives (roles, substitutions and URL links) 
     15   It is loaded for each file thanks to 'rst_epilog' setting in 'conf.py' 
     16 
     17.. toctree:: 
     18   :hidden: 
     19 
     20   release_notes.rst 
     21 
     22.. toctree:: 
     23   :hidden: 
     24   :caption: Getting started 
     25 
     26   install 
     27   configurations 
     28   test_cases 
     29 
     30.. toctree:: 
     31   :hidden: 
     32   :caption: Setup your configuration 
     33 
     34   setup 
     35   diagnostics 
     36   tools 
     37 
     38.. toctree:: 
     39   :hidden: 
     40   :caption: Advanced use 
     41 
     42   zooms 
     43   coarsening 
     44   coupling 
     45   assimilation 
     46   tracers 
     47 
     48.. toctree:: 
     49   :hidden: 
     50   :caption: Glossary 
     51 
     52   definitions 
     53 
     54.. include:: readme.rst 
     55 
     56.. Next headings markup acording to readme.rst 
     57 
     58How to cite NEMO 
     59================ 
     60 
     61.. bibliography:: references.bib 
     62   :all: 
     63   :style: unsrt 
     64   :labelprefix: R 
     65 
     66Disclaimer 
     67========== 
     68 
     69The NEMO source code is freely available and distributed under CeCILL license 
     70(GNU GPL compatible - see ``./LICENSE``). 
     71 
     72You can use, modify and/or redistribute the software under its terms, 
     73but users are provided only with a limited warranty and the software's authors and 
     74the successive licensor's have only limited liability. 

  • NEMO/trunk/doc/rst/source/assimilation.rst

    r10258 r10279  
    1 Data assimilation 
    2 ================= 
    3  
    4 .. include:: .global.rst 
     1************************************** 
     2Data assimilation (OBS/SAO, ASM & TAM) 
     3************************************** 
    54 
    65.. contents:: 
    … …  
    1211- TAM the tangent linear and adjoint model. 
    1312 
    14 Please see the `NEMO reference manual`_ for more details including information about the input file formats and 
     13Please see the `NEMO manual`_ for more details including information about the input file formats and 
    1514the namelist settings. 
    1615 
    17 -------------------------------------- 
    1816Observation and model comparison (OBS) 
    19 -------------------------------------- 
     17====================================== 
    2018 
    2119The observation and model comparison code (OBS) reads in observation files (profile temperature and salinity, 
    … …  
    2826To build with the OBS code active ``key_diaobs`` must be set.  
    2927 
    30 More details in the `NEMO reference manual`_ chapter 12. 
     28More details in the `NEMO manual`_ chapter 12. 
    3129 
    3230Standalone observation operator (SAO) 
    … …  
    4341This is a special version of ``nemogcm.F90`` (which doesn't run the model, but reads in the model fields, and 
    4442observations and runs the OBS code. 
    45 See section 12.4 of the `NEMO reference manual`_. 
     43See section 12.4 of the `NEMO manual`_. 
    4644 
    47 ----------------------------------- 
    4845Apply assimilation increments (ASM) 
    49 ----------------------------------- 
     46=================================== 
    5047 
    5148The ASM code adds the functionality to apply increments to the model variables: 
    … …  
    5653To build the ASM code ``key asminc`` must be set. 
    5754 
    58 More details in the `NEMO reference manual`_ chapter 13. 
     55More details in the `NEMO manual`_ chapter 13. 
    5956 
    60 -------------------------------- 
    6157Tangent linear and adjoint (TAM) 
    62 -------------------------------- 
     58================================ 
    6359 
    6460This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation. 
    65  
    66 .. _NEMO reference manual: http://doi.org/10.5281/zenodo. 

  • NEMO/trunk/doc/rst/source/conf.py

    r10201 r10279  
    2121 
    2222project = 'NEMO' 
    23 copyright = '2018, NEMO System Team' 
     23copyright = '' 
    2424author = 'NEMO System Team' 
    2525 
    … …  
    3939# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 
    4040# ones. 
    41 extensions = ['sphinxcontrib.bibtex'] 
     41extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex'] 
    4242 
    4343# Add any paths that contain templates here, relative to this directory. 
    … …  
    6363# directories to ignore when looking for source files. 
    6464# This pattern also affects html_static_path and html_extra_path . 
    65 exclude_patterns = [] 
     65exclude_patterns = ['global.rst'] 
    6666 
    6767# The name of the Pygments (syntax highlighting) style to use. 
    … …  
    7474# a list of builtin themes. 
    7575# 
    76 html_theme = 'alabaster' 
     76#html_theme = 'alabaster' 
     77html_theme = 'sphinx_rtd_theme' 
    7778 
    7879# Theme options are theme-specific and customize the look and feel of a theme 
    … …  
    8182# 
    8283html_theme_options = { 
    83     'logo': 'NEMO_grey.png', 
    84     'description': 'Community ocean model for multifarious space and time scales', 
    85     'fixed_sidebar': 'true', 
    86 #    'github_user': 'NEMO-ocean', 
    87 #    'github_repo': 'NEMO-examples', 
    88 #    'github_button': 'true', 
    89 #    'github_banner': 'true' 
     84#  Alabaster theme options 
     85#  'logo': 'NEMO_grey.png', 
     86#  'description': 'Community ocean model for multifarious space and time scales', 
     87#  'fixed_sidebar': True, 
    9088} 
    9189 
    … …  
    162160     'Miscellaneous'), 
    163161] 
     162 
     163 
     164# -- Customisation ----------------------------------------------------------- 
     165 
     166import datetime 
     167year = datetime.date.today().year 
     168copyright = '2008-' + str( year ) + ', NEMO Consortium' 
     169 
     170# Link aliases 
     171extlinks = { 
     172   'doi'    : ('http://doi.org/%s'                       , None), 
     173   'forge'  : ('http://forge.ipsl.jussieu.fr/nemo/%s'    , None), 
     174   'github' : ('http://github.com/%s'                    , None), 
     175   'xios'   : ('http://forge.ipsl.jussieu.fr/ioserver/%s', None), 
     176   'website': ('http://www.nemo-ocean.eu/%s'             , None), 
     177   'zenodo' : ('http://zenodo.org/publication/%s'        , None) 
     178} 
     179 
     180# Include common directives for every rst file 
     181rst_epilog = open('global.rst', 'r').read() 

  • NEMO/trunk/doc/rst/source/coupling.rst

    r10201 r10279  
    1 Coupling with other models (OASIS, SAS, ...) 
    2 ============================================ 
    3  
    4 .. include:: .global.rst 
     1********************** 
     2Coupling (OASIS & SAS) 
     3********************** 
    54 
    65NEMO currently exploits OASIS-3-MCT to implement a generalised coupled interface 

  • NEMO/trunk/doc/rst/source/definitions.rst

    r10201 r10279  
    1 =========== 
     1*********** 
    22Definitions 
    3 =========== 
     3*********** 
    44 
    5 .. include:: .global.rst 
    6  
    7 AGRIF 
     5`AGRIF`_ 
    86   *Adaptive Grid Refinement In Fortran*,  
    97   package for the integration of full adaptive mesh refinement features within  
    … …  
    1412   unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework 
    1513 
    16 OASIS 
     14`OASIS`_ 
    1715   *Ocean Atmosphere Sea Ice Soil*,  
    1816   coupling software to synchronise numerical codes representing different components of the climate system 
    … …  
    3129   on/off-line oceanic tracers transport and biogeochemistry models 
    3230 
    33 XIOS 
     31`XIOS`_ 
    3432   *XML Input Output Server*,  
    3533   library dedicated to input/output management of climate code 

  • NEMO/trunk/doc/rst/source/global.rst

    r10277 r10279  
    1 .. Roles (custom styles related to CSS classes) 
     1.. Roles (custom styles related to CSS classes in 'source/_static/style.css') 
    22 
    33.. role:: rstblue 
    … …  
    55.. role:: rstgrey 
    66.. role:: rstgreysup(sup) 
     7.. role:: underline  
     8   :class: underline 
    79 
    8 .. Links 
     10.. Substitutions 
    911 
    10    .. Institutes 
     12.. |OPA| replace:: :rstblue:`NEMO-OPA` 
     13.. |SI3| replace:: :rstgrey:`NEMO-SI`\ :rstgreysup:`3` 
     14.. |TOP| replace:: :rstgreen:`NEMO-TOP/PISCES` 
     15 
     16.. Institutes 
    1117 
    1218.. _CMCC:           http://www.cmcc.it  
    … …  
    1723.. _NERC:           http://nerc.ukri.org 
    1824 
    19    .. Models / Softwares 
     25.. Models / Softwares 
    2026 
    2127.. _AGRIF: http://agrif.imag.fr 
    2228.. _OASIS: http://verc.enes.org/oasis 
     29.. _XIOS:  http://forge.ipsl.jussieu.fr/ioserver 
    2330 
    24    .. NEMO 
     31.. NEMO 
    2532 
    26 .. _NEMO:             http://www.nemo-ocean.eu 
    27 .. _Reference Manual: http://doi.org/10.5281/zenodo.1137733 
    28 .. _Special Issue:    http://www.geosci-model-dev.net/special_issue40.html 
    29 .. _Working Groups:   http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups 
    30  
    31    .. XIOS 
    32  
    33 .. _XIOS:                    http://forge.ipsl.jussieu.fr/ioserver 
    34 .. _XIOS documentation:      http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation 
    35 .. _XIOS users mailing list: http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users 
     33.. _NEMO:          http://www.nemo-ocean.eu 
     34.. _NEMO strategy: http://doi.org/10.5281/zenodo.1471663 
     35.. _NEMO guide:    http://doi.org/10.5281/zenodo.1475325 
     36.. _NEMO manual:   http://doi.org/10.5281/zenodo.1464816 
     37.. _SI3 manual:    http://doi.org/10.5281/zenodo.1471689 
     38.. _TOP manual:    http://doi.org/10.5281/zenodo.1471700 

  • NEMO/trunk/doc/rst/source/interfacing_options.rst

    r10201 r10279  
    33=================== 
    44 
    5 .. include:: .global.rst 
    6  
    7 .. contents:: 
     5.. 
     6   contents:: 
    87   :local: 
    98   :depth: 1 
    109 
    1110.. include:: zooms.rst 
     11 
     12.. bibliography:: zooms.bib 
     13   :all: 
     14   :style: unsrt 
     15   :labelprefix: A 
     16   :keyprefix: a- 
    1217 
    1318---- 
    … …  
    2126---- 
    2227 
    23 .. include:: data_assimilation.rst 
     28.. include:: assimilation.rst 
    2429 
    2530---- 
Note: See TracChangeset for help on using the changeset viewer.