Ignore:
Timestamp:
2018-11-07T12:04:15+01:00 (2 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.