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 11706 – NEMO

Changeset 11706


Ignore:
Timestamp:
2019-10-16T10:51:40+02:00 (4 years ago)
Author:
nicolasmartin
Message:

Update files to be compliant with Python 3 (Python 2 no longer available)
The compilation of the guide is no longer easy with Python 2 with the need of virtual env to
downgrade some dependencies.
Last but not least, Python 2 support will expire by the end of the year.

Location:
NEMO/trunk/doc/rst
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • NEMO/trunk/doc/rst/Makefile

    r10990 r11706  
    1 # Minimal makefile for Sphinx documentation 
     1# Makefile for Sphinx documentation 
    22# 
    33 
    … …  
    55SPHINXOPTS    = 
    66SPHINXBUILD   = sphinx-build 
    7 SPHINXPROJ    = NEMO 
    8 SOURCEDIR     = source 
     7PAPER         = 
    98BUILDDIR      = build 
    109 
    11 # Put it first so that "make" without argument is like "make help". 
     10# Internal variables. 
     11PAPEROPT_a4     = -D latex_paper_size=a4 
     12PAPEROPT_letter = -D latex_paper_size=letter 
     13ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source 
     14# the i18n builder cannot share the environment and doctrees with the others 
     15I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source 
     16 
     17.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 
     18 
    1219help: 
    13    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 
     20   @echo "Please use \`make <target>' where <target> is one of" 
     21   @echo "  html       to make standalone HTML files" 
     22   @echo "  dirhtml    to make HTML files named index.html in directories" 
     23   @echo "  singlehtml to make a single large HTML file" 
     24   @echo "  livehtml   to make an autoupdate HTML export while editing" 
     25   @echo "  pickle     to make pickle files" 
     26   @echo "  json       to make JSON files" 
     27   @echo "  htmlhelp   to make HTML files and a HTML help project" 
     28   @echo "  qthelp     to make HTML files and a qthelp project" 
     29   @echo "  devhelp    to make HTML files and a Devhelp project" 
     30   @echo "  epub       to make an epub" 
     31   @echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 
     32   @echo "  latexpdf   to make LaTeX files and run them through pdflatex" 
     33   @echo "  text       to make text files" 
     34   @echo "  man        to make manual pages" 
     35   @echo "  texinfo    to make Texinfo files" 
     36   @echo "  info       to make Texinfo files and run them through makeinfo" 
     37   @echo "  gettext    to make PO message catalogs" 
     38   @echo "  changes    to make an overview of all changed/added/deprecated items" 
     39   @echo "  linkcheck  to check all external links for integrity" 
     40   @echo "  doctest    to run all doctests embedded in the documentation (if enabled)" 
    1441 
    15 .PHONY: help Makefile 
     42clean: 
     43   -rm -rf $(BUILDDIR)/* 
    1644 
    17 # Catch-all target: route all unknown targets to Sphinx using the new 
    18 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS). 
    19 %: Makefile 
    20    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 
     45html: 
     46   $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 
     47   @echo 
     48   @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 
    2149 
    22 # Watch source directory and rebuild the documentation when a change is detected 
    23 # Browse to 127.0.0.1:8000/NEMO_guide.html 
    24 htmllive: 
    25    sphinx-autobuild $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/htmllive 
     50dirhtml: 
     51   $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 
     52   @echo 
     53   @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 
     54 
     55singlehtml: 
     56   $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 
     57   @echo 
     58   @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 
     59 
     60livehtml: 
     61   sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 
     62   @echo 
     63   @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 
     64 
     65pickle: 
     66   $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 
     67   @echo 
     68   @echo "Build finished; now you can process the pickle files." 
     69 
     70json: 
     71   $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 
     72   @echo 
     73   @echo "Build finished; now you can process the JSON files." 
     74 
     75htmlhelp: 
     76   $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 
     77   @echo 
     78   @echo "Build finished; now you can run HTML Help Workshop with the" \ 
     79         ".hhp project file in $(BUILDDIR)/htmlhelp." 
     80 
     81qthelp: 
     82   $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 
     83   @echo 
     84   @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 
     85         ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 
     86   @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/NEMO.qhcp" 
     87   @echo "To view the help file:" 
     88   @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/NEMO.qhc" 
     89 
     90devhelp: 
     91   $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 
     92   @echo 
     93   @echo "Build finished." 
     94   @echo "To view the help file:" 
     95   @echo "# mkdir -p $$HOME/.local/share/devhelp/NEMO" 
     96   @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/NEMO" 
     97   @echo "# devhelp" 
     98 
     99epub: 
     100   $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 
     101   @echo 
     102   @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 
     103 
     104latex: 
     105   $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
     106   @echo 
     107   @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 
     108   @echo "Run \`make' in that directory to run these through (pdf)latex" \ 
     109         "(use \`make latexpdf' here to do that automatically)." 
     110 
     111latexpdf: 
     112   $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
     113   @echo "Running LaTeX files through pdflatex..." 
     114   $(MAKE) -C $(BUILDDIR)/latex all-pdf 
     115   @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 
     116 
     117text: 
     118   $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 
     119   @echo 
     120   @echo "Build finished. The text files are in $(BUILDDIR)/text." 
     121 
     122man: 
     123   $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 
     124   @echo 
     125   @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 
     126 
     127texinfo: 
     128   $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
     129   @echo 
     130   @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 
     131   @echo "Run \`make' in that directory to run these through makeinfo" \ 
     132         "(use \`make info' here to do that automatically)." 
     133 
     134info: 
     135   $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
     136   @echo "Running Texinfo files through makeinfo..." 
     137   make -C $(BUILDDIR)/texinfo info 
     138   @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 
     139 
     140gettext: 
     141   $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 
     142   @echo 
     143   @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 
     144 
     145changes: 
     146   $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 
     147   @echo 
     148   @echo "The overview file is in $(BUILDDIR)/changes." 
     149 
     150linkcheck: 
     151   $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 
     152   @echo 
     153   @echo "Link check complete; look for any errors in the above output " \ 
     154         "or in $(BUILDDIR)/linkcheck/output.txt." 
     155 
     156doctest: 
     157   $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 
     158   @echo "Testing of doctests in the sources finished, look at the " \ 
     159         "results in $(BUILDDIR)/doctest/output.txt." 

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

    r10991 r11706  
    11# -*- coding: utf-8 -*- 
    22# 
    3 # Configuration file for the Sphinx documentation builder. 
    4 # 
    5 # This file does only contain a selection of the most common options. For a 
    6 # full list see the documentation: 
    7 # http://www.sphinx-doc.org/en/master/config 
    8  
    9 # -- Project information ----------------------------------------------------- 
    10  
    11 project = 'NEMO' 
    12 author = 'NEMO System Team' 
    13  
    14 # The short X.Y version 
    15 version = 'trk' 
    16 # The full version, including alpha/beta/rc tags 
    17 release = 'trunk' 
    18  
    19  
    20 # -- General configuration --------------------------------------------------- 
    21  
    22 # Add any Sphinx extension module names here, as strings. They can be 
    23 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 
    24 # ones. 
    25 extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex'] 
     3# NEMO documentation build configuration file, created by 
     4# sphinx-quickstart on Tue Oct 15 20:13:55 2019. 
     5# 
     6# This file is execfile()d with the current directory set to its containing dir. 
     7# 
     8# Note that not all possible configuration values are present in this 
     9# autogenerated file. 
     10# 
     11# All configuration values have a default; values that are commented out 
     12# serve to show the default. 
     13 
     14import sys, os 
     15 
     16# If extensions (or modules to document with autodoc) are in another directory, 
     17# add these directories to sys.path here. If the directory is relative to the 
     18# documentation root, use os.path.abspath to make it absolute, like shown here. 
     19#sys.path.insert(0, os.path.abspath('.')) 
     20 
     21# -- General configuration ----------------------------------------------------- 
     22 
     23# If your documentation needs a minimal Sphinx version, state it here. 
     24#needs_sphinx = '1.0' 
     25 
     26# Add any Sphinx extension module names here, as strings. They can be extensions 
     27# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 
     28extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex', 'sphinx.ext.todo'] 
    2629 
    2730# Add any paths that contain templates here, relative to this directory. 
    2831templates_path = ['_templates'] 
    2932 
     33# The suffix of source filenames. 
     34source_suffix = '.rst' 
     35 
     36# The encoding of source files. 
     37#source_encoding = 'utf-8-sig' 
     38 
    3039# The master toctree document. 
    3140master_doc = 'NEMO_guide' 
    3241 
     42# General information about the project. 
     43project = u'NEMO' 
     44copyright = u'2019, NEMO Consortium' 
     45 
     46# The version info for the project you're documenting, acts as replacement for 
     47# |version| and |release|, also used in various other places throughout the 
     48# built documents. 
     49# 
     50# The short X.Y version. 
     51version = 'trk' 
     52# The full version, including alpha/beta/rc tags. 
     53release = 'trunk' 
     54 
     55# The language for content autogenerated by Sphinx. Refer to documentation 
     56# for a list of supported languages. 
     57#language = None 
     58 
     59# There are two options for replacing |today|: either, you set today to some 
     60# non-false value, then it is used: 
     61#today = '' 
     62# Else, today_fmt is used as the format for a strftime call. 
     63#today_fmt = '%B %d, %Y' 
     64 
    3365# List of patterns, relative to source directory, that match files and 
    3466# directories to ignore when looking for source files. 
    35 # This pattern also affects html_static_path and html_extra_path . 
    3667exclude_patterns = ['global.rst', 'coarsening.rst'] 
    3768 
     69# The reST default role (used for this markup: `text`) to use for all documents. 
     70#default_role = None 
     71 
     72# If true, '()' will be appended to :func: etc. cross-reference text. 
     73#add_function_parentheses = True 
     74 
     75# If true, the current module name will be prepended to all description 
     76# unit titles (such as .. function::). 
     77#add_module_names = True 
     78 
     79# If true, sectionauthor and moduleauthor directives will be shown in the 
     80# output. They are ignored by default. 
     81#show_authors = False 
     82 
    3883# The name of the Pygments (syntax highlighting) style to use. 
    39 pygments_style = 'sphinx' 
    40  
    41  
    42 # -- Options for HTML output ------------------------------------------------- 
     84pygments_style = 'emacs' 
     85 
     86# A list of ignored prefixes for module index sorting. 
     87#modindex_common_prefix = [] 
     88 
     89 
     90# -- Options for HTML output --------------------------------------------------- 
    4391 
    4492# The theme to use for HTML and HTML Help pages.  See the documentation for 
    4593# a list of builtin themes. 
    46 # 
    4794html_theme = 'sphinx_rtd_theme' 
    4895 
    … …  
    5097# further.  For a list of options available for each theme, see the 
    5198# documentation. 
    52 # 
    53 html_theme_options = {} 
     99#html_theme_options = {} 
     100 
     101# Add any paths that contain custom themes here, relative to this directory. 
     102#html_theme_path = [] 
     103 
     104# The name for this set of Sphinx documents.  If None, it defaults to 
     105# "<project> v<release> documentation". 
     106#html_title = None 
     107 
     108# A shorter title for the navigation bar.  Default is the same as html_title. 
     109#html_short_title = None 
     110 
     111# The name of an image file (relative to this directory) to place at the top 
     112# of the sidebar. 
     113#html_logo = None 
     114 
     115# The name of an image file (within the static path) to use as favicon of the 
     116# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32 
     117# pixels large. 
     118html_favicon = '_static/ORCA.ico' 
    54119 
    55120# Add any paths that contain custom static files (such as style sheets) here, 
    … …  
    58123html_static_path = ['_static'] 
    59124 
    60 html_favicon = '_static/ORCA.ico' 
    61  
    62  
    63 # -- Options for LaTeX output ------------------------------------------------ 
     125# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 
     126# using the given strftime format. 
     127#html_last_updated_fmt = '%b %d, %Y' 
     128 
     129# If true, SmartyPants will be used to convert quotes and dashes to 
     130# typographically correct entities. 
     131#html_use_smartypants = True 
     132 
     133# Custom sidebar templates, maps document names to template names. 
     134#html_sidebars = {} 
     135 
     136# Additional templates that should be rendered to pages, maps page names to 
     137# template names. 
     138#html_additional_pages = {} 
     139 
     140# If false, no module index is generated. 
     141#html_domain_indices = True 
     142 
     143# If false, no index is generated. 
     144#html_use_index = True 
     145 
     146# If true, the index is split into individual pages for each letter. 
     147#html_split_index = False 
     148 
     149# If true, links to the reST sources are added to the pages. 
     150#html_show_sourcelink = True 
     151 
     152# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 
     153#html_show_sphinx = True 
     154 
     155# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 
     156#html_show_copyright = True 
     157 
     158# If true, an OpenSearch description file will be output, and all pages will 
     159# contain a <link> tag referring to it.  The value of this option must be the 
     160# base URL from which the finished HTML is served. 
     161#html_use_opensearch = '' 
     162 
     163# This is the file name suffix for HTML files (e.g. ".xhtml"). 
     164#html_file_suffix = None 
     165 
     166# Output file base name for HTML help builder. 
     167htmlhelp_basename = 'NEMOdoc' 
     168 
     169 
     170# -- Options for LaTeX output -------------------------------------------------- 
    64171 
    65172latex_elements = { 
    66     # The paper size ('letterpaper' or 'a4paper'). 
    67     # 
    68     # 'papersize': 'letterpaper', 
    69  
    70     # The font size ('10pt', '11pt' or '12pt'). 
    71     # 
    72     # 'pointsize': '10pt', 
    73  
    74     # Additional stuff for the LaTeX preamble. 
    75     # 
    76     # 'preamble': '', 
    77  
    78     # Latex figure (float) alignment 
    79     # 
    80     # 'figure_align': 'htbp', 
     173# The paper size ('letterpaper' or 'a4paper'). 
     174#'papersize': 'letterpaper', 
     175 
     176# The font size ('10pt', '11pt' or '12pt'). 
     177#'pointsize': '10pt', 
     178 
     179# Additional stuff for the LaTeX preamble. 
     180#'preamble': '', 
    81181} 
    82182 
    83183# Grouping the document tree into LaTeX files. List of tuples 
    84 # (source start file, target name, title, 
    85 #  author, documentclass [howto, manual, or own class]). 
     184# (source start file, target name, title, author, documentclass [howto/manual]). 
    86185latex_documents = [ 
    87     (master_doc, 'NEMO_guide.tex', 'NEMO Quick Start Guide', 
    88      'NEMO System Team', 'howto'), 
     186  ('NEMO_guide', 'NEMO_guide.tex', u'NEMO Quick Start Guide', 
     187   u'NEMO Consortium', 'howto'), 
    89188] 
    90189 
    91  
    92 # -- Customisation ----------------------------------------------------------- 
     190# The name of an image file (relative to this directory) to place at the top of 
     191# the title page. 
     192#latex_logo = None 
     193 
     194# For "manual" documents, if this is true, then toplevel headings are parts, 
     195# not chapters. 
     196#latex_use_parts = False 
     197 
     198# If true, show page references after internal links. 
     199#latex_show_pagerefs = False 
     200 
     201# If true, show URL addresses after external links. 
     202#latex_show_urls = False 
     203 
     204# Documents to append as an appendix to all manuals. 
     205#latex_appendices = [] 
     206 
     207# If false, no module index is generated. 
     208#latex_domain_indices = True 
     209 
     210 
     211# -- Options for manual page output -------------------------------------------- 
     212 
     213# One entry per manual page. List of tuples 
     214# (source start file, name, description, authors, manual section). 
     215man_pages = [ 
     216    ('NEMO_guide', 'nemo', u'NEMO Documentation', 
     217     [u'NEMO System Team'], 1) 
     218] 
     219 
     220# If true, show URL addresses after external links. 
     221#man_show_urls = False 
     222 
     223 
     224# -- Options for Texinfo output ------------------------------------------------ 
     225 
     226# Grouping the document tree into Texinfo files. List of tuples 
     227# (source start file, target name, title, author, 
     228#  dir menu entry, description, category) 
     229texinfo_documents = [ 
     230  ('NEMO_guide', 'NEMO', u'NEMO Documentation', 
     231   u'NEMO System Team', 'NEMO', 'One line description of project.', 
     232   'Miscellaneous'), 
     233] 
     234 
     235# Documents to append as an appendix to all manuals. 
     236#texinfo_appendices = [] 
     237 
     238# If false, no module index is generated. 
     239#texinfo_domain_indices = True 
     240 
     241# How to display URL addresses: 'footnote', 'no', or 'inline'. 
     242#texinfo_show_urls = 'footnote' 
     243 
     244# -- Customisation ------------------------------------------------------------- 
    93245 
    94246# Timestamping 
    … …  
    99251# Link aliases 
    100252extlinks = { 
    101    'doi'    : ('https://doi.org/%s'                       , None), 
    102    'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'    , None), 
    103    'github' : ('https://github.com/%s'                    , None), 
    104    'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s', None), 
    105    'website': ('https://www.nemo-ocean.eu/%s'             , None), 
    106    'zenodo' : ('https://zenodo.org/publication/%s'        , None) 
     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) 
    107259} 
    108260 
Note: See TracChangeset for help on using the changeset viewer.