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 11713 for NEMO/trunk/doc – NEMO

Changeset 11713 for NEMO/trunk/doc


Ignore:
Timestamp:
2019-10-17T17:49:19+02:00 (5 years ago)
Author:
nicolasmartin
Message:

Revamp TOP README and implement a TODO list
Review tracers.rst by adding snippets of source files
Add drafthtml target for Makefile related to draft building tag for sphinx-build to
display todo items at the top of the guide homepage

Misc:

  • Use dedicated :file: role instead of ... for file or directory
  • Update BibTeX entries of NEMO reference publications by using :title: role
  • Dump of RELEASE_NOTES.rst
  • New file todos.rst to list all items declared with todo directive
  • Modify conf.py to add a conditional test for draft tag
Location:
NEMO/trunk/doc/rst
Files:
1 added
7 edited

Legend:

Unmodified
Added
Removed

  • NEMO/trunk/doc/rst/Makefile

    r11706 r11713  
    1515I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source 
    1616 
    17 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 
     17.PHONY: help clean html dirhtml drafthtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 
    1818 
    1919help: 
    … …  
    2121   @echo "  html       to make standalone HTML files" 
    2222   @echo "  dirhtml    to make HTML files named index.html in directories" 
     23   @echo "  drafthtml  to make an autoupdate HTML export while editing (todo list included)" 
    2324   @echo "  singlehtml to make a single large HTML file" 
    24    @echo "  livehtml   to make an autoupdate HTML export while editing" 
    2525   @echo "  pickle     to make pickle files" 
    2626   @echo "  json       to make JSON files" 
    … …  
    4444 
    4545html: 
    46    $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 
     46   $(SPHINXBUILD)   -b html          $(ALLSPHINXOPTS) $(BUILDDIR)/html 
    4747   @echo 
    4848   @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 
    4949 
    5050dirhtml: 
    51    $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 
     51   $(SPHINXBUILD)   -b dirhtml      $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 
    5252   @echo 
    5353   @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 
    5454 
     55drafthtml: 
     56   sphinx-autobuild -b html -t draft $(ALLSPHINXOPTS) $(BUILDDIR)/drafthtml 
     57   @echo 
     58   @echo "Build finished. The HTML pages are in $(BUILDDIR)/drafthtml." 
     59 
    5560singlehtml: 
    56    $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 
     61   $(SPHINXBUILD)   -b singlehtml    $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 
    5762   @echo 
    5863   @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 
    5964 
    60 livehtml: 
    61    sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 
    62    @echo 
    63    @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 
    64  
    6565pickle: 
    66    $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 
     66   $(SPHINXBUILD)   -b pickle        $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 
    6767   @echo 
    6868   @echo "Build finished; now you can process the pickle files." 
    6969 
    7070json: 
    71    $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 
     71   $(SPHINXBUILD)   -b json          $(ALLSPHINXOPTS) $(BUILDDIR)/json 
    7272   @echo 
    7373   @echo "Build finished; now you can process the JSON files." 
    7474 
    7575htmlhelp: 
    76    $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 
     76   $(SPHINXBUILD)   -b htmlhelp      $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 
    7777   @echo 
    7878   @echo "Build finished; now you can run HTML Help Workshop with the" \ 
    … …  
    8080 
    8181qthelp: 
    82    $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 
     82   $(SPHINXBUILD)   -b qthelp        $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 
    8383   @echo 
    8484   @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 
    … …  
    8989 
    9090devhelp: 
    91    $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 
     91   $(SPHINXBUILD)   -b devhelp      $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 
    9292   @echo 
    9393   @echo "Build finished." 
    … …  
    9898 
    9999epub: 
    100    $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 
     100   $(SPHINXBUILD)   -b epub          $(ALLSPHINXOPTS) $(BUILDDIR)/epub 
    101101   @echo 
    102102   @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 
    103103 
    104104latex: 
    105    $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
     105   $(SPHINXBUILD)   -b latex        $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
    106106   @echo 
    107107   @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 
    … …  
    110110 
    111111latexpdf: 
    112    $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
     112   $(SPHINXBUILD)   -b latex        $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
    113113   @echo "Running LaTeX files through pdflatex..." 
    114114   $(MAKE) -C $(BUILDDIR)/latex all-pdf 
    … …  
    116116 
    117117text: 
    118    $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 
     118   $(SPHINXBUILD)   -b text          $(ALLSPHINXOPTS) $(BUILDDIR)/text 
    119119   @echo 
    120120   @echo "Build finished. The text files are in $(BUILDDIR)/text." 
    121121 
    122122man: 
    123    $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 
     123   $(SPHINXBUILD)   -b man          $(ALLSPHINXOPTS) $(BUILDDIR)/man 
    124124   @echo 
    125125   @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 
    126126 
    127127texinfo: 
    128    $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
     128   $(SPHINXBUILD)   -b texinfo      $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
    129129   @echo 
    130130   @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 
    … …  
    133133 
    134134info: 
    135    $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
     135   $(SPHINXBUILD)   -b texinfo      $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
    136136   @echo "Running Texinfo files through makeinfo..." 
    137137   make -C $(BUILDDIR)/texinfo info 
    … …  
    139139 
    140140gettext: 
    141    $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 
     141   $(SPHINXBUILD)   -b gettext      $(I18NSPHINXOPTS) $(BUILDDIR)/locale 
    142142   @echo 
    143143   @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 
    144144 
    145145changes: 
    146    $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 
     146   $(SPHINXBUILD)   -b changes      $(ALLSPHINXOPTS) $(BUILDDIR)/changes 
    147147   @echo 
    148148   @echo "The overview file is in $(BUILDDIR)/changes." 
    149149 
    150150linkcheck: 
    151    $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 
     151   $(SPHINXBUILD)   -b linkcheck    $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 
    152152   @echo 
    153153   @echo "Link check complete; look for any errors in the above output " \ 
    … …  
    155155 
    156156doctest: 
    157    $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 
     157   $(SPHINXBUILD)   -b doctest      $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 
    158158   @echo "Testing of doctests in the sources finished, look at the " \ 
    159159         "results in $(BUILDDIR)/doctest/output.txt." 

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

    r11707 r11713  
    1212   ", for paragraphs 
    1313 
    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' 
     14   'global.rst' contains a list of roles, substitutions and URL links for the guide. 
     15   It is loaded for each file with the 'rst_epilog' setting in 'conf.py' 
    1616 
    1717.. toctree:: 
    … …  
    4949   glossary 
    5050 
     51:Release:  |release| 
     52 
     53.. only:: draft 
     54 
     55   .. include:: todos.rst 
     56 
    5157.. include:: readme.rst 
    52  
    53 .. Next headings markup acording to readme.rst 
    54  
    55 Disclaimer 
    56 ========== 
    57  
    58 The NEMO source code is freely available and distributed under CeCILL license 
    59 (GNU GPL compatible - see ``./LICENSE``). 
    60  
    61 You can use, modify and/or redistribute the software under its terms, 
    62 but users are provided only with a limited warranty and the software's authors and 
    63 the successive licensor's have only limited liability. 

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

    r11707 r11713  
    1 **************** 
    2 How to cite NEMO 
    3 **************** 
     1*********** 
     2How to cite 
     3*********** 
    44 
    5  
    6 |NEMO-OCE| :cite:`NEMO_manual` 
    7  
    8    | "**NEMO ocean engine**" 
    9    | Gurvan Madec and NEMO System Team 
    10    | *Scientific Notes of Climate Modelling Center*, **27** 
    11    | ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL) 
    12    | |DOI man OCE|_ 
     5|NEMO-OCE| 
     6   :title:`NEMO ocean engine`, 
     7   NEMO System Team, 
     8   Scientific Notes of Climate Modelling Center, 27, 
     9   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL), 
     10   :doi:`10.5281/zenodo.1464816` 
    1311 
    1412.. literalinclude:: references.bib 
    1513   :language: bibtex 
    16    :lines:    1-15 
     14   :lines:    1-9 
    1715   :caption:  BibTeX source for NEMO manual 
    1816 
    19 |NEMO-ICE| :cite:`SI3_manual` 
    20  
    21    | "**Sea Ice modelling Integrated Initiative (SI** :sup:`3` **) -- The NEMO sea ice engine**" 
    22    | NEMO Sea Ice Working Group 
    23    | *Scientific Notes of Climate Modelling Center*, **31** 
    24    | ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL) 
    25    | |DOI man ICE| 
     17|NEMO-ICE| 
     18   :title:`Sea Ice modelling Integrated Initiative (SI`\ :sup:`3`\ :title:`) -- 
     19   The NEMO sea ice engine`, 
     20   NEMO Sea Ice Working Group, 
     21   Scientific Notes of Climate Modelling Center, 31, 
     22   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL), 
     23   :doi:`10.5281/zenodo.1471689` 
    2624 
    2725.. warning::  No official publication yet 
    … …  
    2927.. literalinclude:: references.bib 
    3028   :language: bibtex 
    31    :lines:    17-33 
     29   :lines:    13-21 
    3230   :caption:  BibTeX source for SI\ :sup:`3` manual 
    3331 
    34 |NEMO-MBG| :cite:`TOP_manual` 
    35  
    36    | "**Tracer in Ocean Paradigm (TOP) -- The NEMO passive tracer engine**" 
    37    | NEMO TOP Working Group 
    38    | *Scientific Notes of Climate Modelling Center*, **28** 
    39    | ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL) 
    40    | |DOI man MBG| 
     32|NEMO-MBG| 
     33   :title:`Tracer in Ocean Paradigm (TOP) -- The NEMO passive tracer engine`, 
     34   NEMO TOP Working Group, 
     35   Scientific Notes of Climate Modelling Center, 28, 
     36   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL), 
     37   :doi:`10.5281/zenodo.1471700` 
    4138 
    4239.. warning::  No official publication yet 
    … …  
    4441.. literalinclude:: references.bib 
    4542   :language: bibtex 
    46    :lines:    37-49 
     43   :lines:    25-33 
    4744   :caption:  BibTeX source for TOP manual 
    48  
    49 References 
    50 ========== 
    51  
    52 .. bibliography:: references.bib 
    53    :style:       unsrt 
    54    :labelprefix: R 

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

    r11706 r11713  
    2626# Add any Sphinx extension module names here, as strings. They can be extensions 
    2727# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 
    28 extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex', 'sphinx.ext.todo'] 
     28extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex', 'sphinx.ext.todo', 'sphinxmark'] 
    2929 
    3030# Add any paths that contain templates here, relative to this directory. 
    … …  
    251251# Link aliases 
    252252extlinks = { 
    253    'doi'    : ('https://doi.org/%s'                       , None), 
    254    'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'    , None), 
    255    'github' : ('https://github.com/%s'                    , None), 
    256    'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s', None), 
    257    'website': ('https://www.nemo-ocean.eu/%s'             , None), 
    258    'zenodo' : ('https://zenodo.org/publication/%s'        , None) 
     253   'doi'    : ('https://doi.org/%s'                       , 'doi:'), 
     254   'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'    ,   None), 
     255   'github' : ('https://github.com/%s'                    ,   None), 
     256   'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s',   None), 
     257   'website': ('https://www.nemo-ocean.eu/%s'             ,   None), 
     258   'zenodo' : ('https://zenodo.org/publication/%s'        ,   None) 
    259259} 
    260260 
    … …  
    266266revision = subprocess.check_output("svnversion").decode("utf-8") 
    267267rst_prolog = '.. |revision| replace:: %s' % revision 
     268 
     269# Todo 
     270if tags.has('draft'): 
     271    sphinxmark_enable = True 
     272    todo_include_todos = True 
     273    todo_emit_warnings = True 

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

    r11707 r11713  
    4040To build the SAO use makenemo. 
    4141This means compiling NEMO once (in the normal way) for the chosen configuration. 
    42 Then include ``SAO`` at the end of the relevant line in ``cfg.txt`` file. 
    43 Then recompile with the replacement main program in ``./src/SAO``. 
    44 This is a special version of ``nemogcm.F90`` (which doesn't run the model, 
     42Then include ``SAO`` at the end of the relevant line in :file:`cfg.txt` file. 
     43Then recompile with the replacement main program in :file:`./src/SAO`. 
     44This is a special version of :file:`nemogcm.F90` (which doesn't run the model, 
    4545but reads in the model fields, and observations and runs the OBS code. 
    4646See "Standalone observation operator (``SAO``)" section in |DOI man OCE|_. 

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

    r11707 r11713  
    55.. role:: grey 
    66.. role:: greysup(sup) 
    7 .. role: underline 
    8 ..   :class: underline 
    97 
    108.. Substitutions 
    119 
    12 .. |NEMO-OCE| replace:: :blue:`NEMO-OCE (Ocean dynamics)` 
    13 .. |NEMO-ICE| replace:: :grey:`NEMO-SI`\ :greysup:`3`\ :grey:`(Sea Ice)` 
    14 .. |NEMO-MBG| replace:: :green:`NEMO-TOP/PISCES (Biogeochemistry)` 
     10.. |NEMO-OCE| replace::  :blue:`NEMO-OCE (Ocean dynamics)` 
     11.. |OCE|      replace::  :blue:`NEMO-OCE` 
     12.. |NEMO-ICE| replace::  :grey:`NEMO-SI`\ :greysup:`3`  :grey:`(Sea Ice)` 
     13.. |ICE|      replace::  :grey:`NEMO-SI`\ :greysup:`3` 
     14.. |NEMO-MBG| replace:: :green:`NEMO-TOP/PISCES (Tracers)` 
     15.. |MBG|      replace:: :green:`NEMO-TOP/PISCES` 
    1516 
    1617.. External links 
    … …  
    3738.. _EGU: http://www.egu.eu 
    3839.. _Special Issue: https://www.geosci-model-dev.net/special_issue40.html 
     40.. _BFM man: https://cmcc-foundation.github.io/www.bfm-community.eu/files/bfm-nemo-manual_r1.0_201508.pdf 
    3941 
    4042.. DOI 

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

    r11707 r11713  
    33******** 
    44 
    5 `AGRIF`_ 
    6    *Adaptive Grid Refinement In Fortran*, 
    7    package for the integration of full adaptive mesh refinement features within 
    8    an existing multidimensional finite difference model 
     5.. glossary:: 
    96 
    10 SI\ :sup:`3`\ 
    11    *Sea Ice Integrated Initiative*, 
    12    unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework 
     7   `AGRIF`_ 
     8      *Adaptive Grid Refinement In Fortran*, 
     9      package for the integration of full adaptive mesh refinement features within 
     10      an existing multidimensional finite difference model 
    1311 
    14 `OASIS`_ 
    15    *Ocean Atmosphere Sea Ice Soil*, 
    16    coupling software to synchronise numerical codes representing different components of the climate system 
     12   SI\ :sup:`3`\ 
     13      *Sea Ice Integrated Initiative*, 
     14      unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework 
    1715 
    18 PISCES 
    19    *Pelagic Interactions Scheme for Carbon and Ecosystem Studies*, 
    20    biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients 
     16   `OASIS`_ 
     17      *Ocean Atmosphere Sea Ice Soil*, 
     18      coupling software to synchronise numerical codes representing different components of the climate system 
    2119 
    22 TAM 
    23    *Tangent linear and Adjoint Model*, 
    24    tools to analyse and control the NEMO dynamical core for a wide range of applications such as 
    25    sensitivity analysis, parameter estimation, vectors computation or data assimilation. 
     20   PISCES 
     21      *Pelagic Interactions Scheme for Carbon and Ecosystem Studies*, 
     22      biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients 
    2623 
    27 TOP 
    28    *Tracers in Ocean Paradigm*, 
    29    on/off-line oceanic tracers transport and biogeochemistry models 
     24   TAM 
     25      *Tangent linear and Adjoint Model*, 
     26      tools to analyse and control the NEMO dynamical core for a wide range of applications such as 
     27      sensitivity analysis, parameter estimation, vectors computation or data assimilation. 
    3028 
    31 `XIOS`_ 
    32    *XML Input Output Server*, 
    33    library dedicated to input/output management of climate code 
     29   TOP 
     30      *Tracers in Ocean Paradigm*, 
     31      on/off-line oceanic tracers transport and biogeochemistry models 
     32 
     33   `XIOS`_ 
     34      *XML Input Output Server*, 
     35      library dedicated to input/output management of climate code 
Note: See TracChangeset for help on using the changeset viewer.