From 21caccede072b064ee1e9191c50ed00255fff5fe Mon Sep 17 00:00:00 2001
From: Johan Fourdrinoy <johan.fourdrinoy@edf.fr>
Date: Wed, 5 Feb 2025 13:45:44 +0100
Subject: [PATCH] [mascaret][doc] Add reference documentation
---
NEWS.txt | 2 +
.../mascaret/reference/mascaret_reference.tex | 58 ++++++++++
scripts/python3/doc_telemac.py | 103 ++++++++++--------
3 files changed, 115 insertions(+), 48 deletions(-)
create mode 100644 documentation/mascaret/reference/mascaret_reference.tex
diff --git a/NEWS.txt b/NEWS.txt
index 0f5cc96781..faeab047ff 100644
--- a/NEWS.txt
+++ b/NEWS.txt
@@ -1,6 +1,8 @@
Latest changes
==============
+MASCARET: Reference Documentation has been added
+
TELEMAC-2D: better time step managment in the finite volume kernel.
- allowed constant time step
- allowed variable time step with CFL > 0.9 (before: was forced to 0.9);
diff --git a/documentation/mascaret/reference/mascaret_reference.tex b/documentation/mascaret/reference/mascaret_reference.tex
new file mode 100644
index 0000000000..a98d12f9da
--- /dev/null
+++ b/documentation/mascaret/reference/mascaret_reference.tex
@@ -0,0 +1,58 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Telemac Documentation
+% Example of the TelemacDoc class
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%----------------------------------------------------------------------------------------
+% PACKAGES AND OTHER DOCUMENT CONFIGURATIONS
+%----------------------------------------------------------------------------------------
+\documentclass[Mascaret]{../../data/TelemacDoc} % Default font size and left-justified equations
+%\documentclass[Telemac2D,french]{TelemacDoc} % Default font size and left-justified equations in french
+
+\begin{document}
+
+\let\cleardoublepage\clearpage
+
+%----------------------------------------------------------------------------------------
+% TITLE PAGE
+%----------------------------------------------------------------------------------------
+\title{Mascaret-Tracer-Courlis}
+\subtitle{Reference Manual}
+\version{\telmaversion}
+\date{\today}
+\maketitle
+\clearpage
+
+
+%----------------------------------------------------------------------------------------
+% COPYRIGHT PAGE
+%----------------------------------------------------------------------------------------
+
+\newpage
+
+\thispagestyle{empty}
+
+\TelemacCopyright{}
+
+
+%----------------------------------------------------------------------------------------
+% TABLE OF CONTENTS
+%----------------------------------------------------------------------------------------
+
+
+\pagestyle{empty} % No headers
+
+\tableofcontents% Print the table of contents itself
+
+%\cleardoublepage % Forces the first chapter to start on an odd page so it's on the right
+
+\pagestyle{fancy} % Print headers again
+
+%----------------------------------------------------------------------------------------
+% The whole thing
+%----------------------------------------------------------------------------------------
+
+\input{./latex/Corpus}
+
+\end{document}
diff --git a/scripts/python3/doc_telemac.py b/scripts/python3/doc_telemac.py
index 69fc9588b2..3615b37caa 100755
--- a/scripts/python3/doc_telemac.py
+++ b/scripts/python3/doc_telemac.py
@@ -36,6 +36,7 @@ MISC_LIST = ['developer_guide',
'doxypydocs',
'notebooks']
+
def clean_doc(doc_dir, fullclean):
"""
@brief Remove latex temporary files
@@ -51,6 +52,7 @@ def clean_doc(doc_dir, fullclean):
if fullclean and fle.endswith(".pdf"):
remove(fle)
+
def generate_list_variables(doc_dir):
"""
Generates in latex format list of variables for each telapy module
@@ -100,7 +102,7 @@ $content
# Getting info for each variable
for i in range(nb_var):
tmp_varname, tmp_varinfo, error = \
- get_var_info(i+1, var_len, info_len)
+ get_var_info(i+1, var_len, info_len)
if error != 0:
raise TelemacException(
"Error when getting info for var {}".format(i+1))
@@ -118,6 +120,7 @@ $content
ffile.write(list_variable_template.substitute(
mod=module, content=content))
+
def compiletex(texfile, version, verbose):
"""
@brief Full procedure for compiling a LaTeX file
@@ -133,11 +136,10 @@ def compiletex(texfile, version, verbose):
bib_cmd = "bibtex {}_{}.aux".format(texfile, version)
else:
tex_cmd = \
- "openout_any=a pdflatex --jobname={tex}_{version} {tex}.tex >latex_run.log 2>&1"\
- .format(tex=texfile, version=version)
+ "openout_any=a pdflatex --jobname={tex}_{version} {tex}.tex >latex_run.log 2>&1"\
+ .format(tex=texfile, version=version)
bib_cmd = "bibtex {}_{}.aux >bib_run.log 2>&1".format(texfile, version)
-
# First compilation
mes = Messages(size=10)
tail, code = mes.run_cmd(tex_cmd, False)
@@ -146,10 +148,10 @@ def compiletex(texfile, version, verbose):
if verbose:
log = ''
else:
- log = '\noutput:\n{}'.format(\
- '\n'.join(get_file_content('latex_run.log')[-20:]))
- raise TelemacException(\
- 'Latex compilation failed\n{}\n{}'\
+ log = '\noutput:\n{}'.format(
+ '\n'.join(get_file_content('latex_run.log')[-20:]))
+ raise TelemacException(
+ 'Latex compilation failed\n{}\n{}'
.format(tail, log))
# Bibtex compilation
@@ -162,10 +164,10 @@ def compiletex(texfile, version, verbose):
if verbose:
log = ''
else:
- log = '\noutput:\n{}'.format(\
- '\n'.join(get_file_content('latex_run.log')[-20:]))
- raise TelemacException(\
- 'Latex compilation failed\n{}\n{}'\
+ log = '\noutput:\n{}'.format(
+ '\n'.join(get_file_content('latex_run.log')[-20:]))
+ raise TelemacException(
+ 'Latex compilation failed\n{}\n{}'
.format(tail, log))
# Second compilation
@@ -175,10 +177,10 @@ def compiletex(texfile, version, verbose):
if verbose:
log = ''
else:
- log = '\noutput:\n{}'.format(\
- '\n'.join(get_file_content('bib_run.log')[-20:]))
- raise TelemacException(\
- 'Latex compilation failed\n{}\n{}'\
+ log = '\noutput:\n{}'.format(
+ '\n'.join(get_file_content('bib_run.log')[-20:]))
+ raise TelemacException(
+ 'Latex compilation failed\n{}\n{}'
.format(tail, log))
# Third compilation
@@ -188,13 +190,15 @@ def compiletex(texfile, version, verbose):
if verbose:
log = ''
else:
- log = '\noutput:\n{}'.format(\
- '\n'.join(get_file_content('latex_run.log')[-20:]))
- raise TelemacException(\
- 'Latex compilation failed\n{}\n{}'\
+ log = '\noutput:\n{}'.format(
+ '\n'.join(get_file_content('latex_run.log')[-20:]))
+ raise TelemacException(
+ 'Latex compilation failed\n{}\n{}'
.format(tail, log))
#
+
+
def create_case_list_file(doc_dir, val_dir, cfg_val, cleanup):
"""
@brief Creates the CASELIST.tex which includes
@@ -292,9 +296,10 @@ def generate_ref_from_dict(exe_path, dictionary, latex_file, lng,
else:
log = '\n\nHere is the log:\n'\
+ '\n'.join(get_file_content(log_file))
- raise TelemacException(\
- 'Could not generated data from dictionary '
- + '{}'.format(log))
+ raise TelemacException(
+ 'Could not generated data from dictionary '
+ + '{}'.format(log))
+
def compile_doc(doc_dir, doc_name, version, cleanup, fullcleanup, verbose):
"""
@@ -317,6 +322,7 @@ def compile_doc(doc_dir, doc_name, version, cleanup, fullcleanup, verbose):
# compiling the texfile
compiletex(doc_name, version, verbose)
+
def generate_notebook_html(doc_dir, notebook_dir, verbose):
"""
Generate an html layout of the notebooks using ipython nbconvert
@@ -355,10 +361,10 @@ def generate_notebook_html(doc_dir, notebook_dir, verbose):
log_lvl = 'ERROR'
cmd = "jupyter nbconvert --to html --log-level={log_lvl} "\
"--output-dir={out_dir} --output={output} {nb}"\
- .format(log_lvl=log_lvl, out_dir=out_dir,
- output="tmp.html", nb=notebook)
- print(" ~> Converting "+\
- path.join(root.replace(notebook_dir, '')[1:], ffile))
+ .format(log_lvl=log_lvl, out_dir=out_dir,
+ output="tmp.html", nb=notebook)
+ print(" ~> Converting " +
+ path.join(root.replace(notebook_dir, '')[1:], ffile))
if verbose:
print(cmd)
# Running conversion
@@ -405,23 +411,24 @@ def compile_doxygen(doxy_file, verbose):
if verbose:
log = ''
else:
- log = '\noutput:\n{}'.format(\
- '\n'.join(get_file_content('Doxygen_run.log')[-20:]))
- raise TelemacException(\
- 'Doxygen failed\n{}\n{}'\
+ log = '\noutput:\n{}'.format(
+ '\n'.join(get_file_content('Doxygen_run.log')[-20:]))
+ raise TelemacException(
+ 'Doxygen failed\n{}\n{}'
.format(tail, log))
html_file = path.join(doxy_dir, 'html', 'index.html')
- print(" To see documentation run (replace firefox by your "\
+ print(" To see documentation run (replace firefox by your "
"internet browser):\n firefox {}".format(html_file))
doxy_warning_log = path.join(doxy_dir, 'Doxygen_warning.log')
if stat(doxy_warning_log).st_size != 0:
- print('There seems to be some doxygen warnings see:\n{}'\
+ print('There seems to be some doxygen warnings see:\n{}'
.format(doxy_warning_log))
+
def generate_doxygen(doxydoc, verbose):
"""
Generate the Doxygen documentation (In html) for the Python and the sources
@@ -445,6 +452,7 @@ def generate_doxygen(doxydoc, verbose):
compile_doxygen(doxy_file, verbose)
+
def main():
"""
Main program for the compilation of the documentation of
@@ -467,13 +475,13 @@ use the options --validation/reference/user/release/theory to compile only one
parser.add_argument(
"-m", "--modules",
dest="modules", default='',
- help="specify the list modules (, separated), default is all of them "+
+ help="specify the list modules (, separated), default is all of them " +
"from {"+",".join(MODULE_LIST)+"}")
parser.add_argument(
"-M", "--misc",
dest="misc", default='',
help="specify the list of misc documentation (, separated) to compile, "
- "default is all of them "+
+ "default is all of them " +
"from {"+",".join(MISC_LIST)+"}")
parser.add_argument(
"--validation", action="store_true",
@@ -587,7 +595,6 @@ use the options --validation/reference/user/release/theory to compile only one
todo.append('validation')
if options.reference or doall:
if code_name not in ['telapy',
- 'mascaret',
'nestor',
'coupling']:
# Path to the dictionary
@@ -600,20 +607,21 @@ use the options --validation/reference/user/release/theory to compile only one
# English only for now
lng = '2'
# Path to bin directory
- exe_path = path.join(\
- root, 'builds', CFGS.cfgname,
- 'bin', 'damocles'+cfg['SYSTEM']['sfx_exe'])
+ exe_path = path.join(
+ root, 'builds', CFGS.cfgname,
+ 'bin', 'damocles'+cfg['SYSTEM']['sfx_exe'])
if code_name == 'courlis':
dictionary = path.join(root,
'sources',
'mascaret',
'mascaret.dico')
+ generate_ref_from_dict(
+ exe_path, dictionary, latex_file, lng,
+ options.cleanup or options.fullcleanup,
+ options.verbose)
print(dictionary)
- generate_ref_from_dict(\
- exe_path, dictionary, latex_file, lng,
- options.cleanup or options.fullcleanup,
- options.verbose)
todo.append('reference')
+
if options.user or doall:
if code_name not in ['mascaret']:
# Normal Compilation of a LaTeX file
@@ -623,7 +631,7 @@ use the options --validation/reference/user/release/theory to compile only one
if code_name in ['telemac3d', 'mascaret', 'waqtel', 'courlis']:
todo.append('theory_guide')
for doc_type in todo:
- print('\n ~> Compilation of the {} documentation'\
+ print('\n ~> Compilation of the {} documentation'
.format(doc_type))
doc_dir = path.join(root, 'documentation',
code_name, doc_type)
@@ -645,7 +653,7 @@ use the options --validation/reference/user/release/theory to compile only one
return 1
if not (options.cleanup or options.fullcleanup):
output_mess += ' - Created %s_%s_%s.pdf\n' % \
- (code_name, doc_type, version)
+ (code_name, doc_type, version)
# List of the other documentation
print('\nCompilation of the documentation for Misc'
+ '\n'+'~'*72)
@@ -677,11 +685,10 @@ use the options --validation/reference/user/release/theory to compile only one
if not (options.cleanup or options.fullcleanup):
if doc not in ['notebooks', 'doxydocs', 'doxypydocs']:
output_mess += ' - Created %s for %s.pdf\n' % \
- (doc, version)
+ (doc, version)
else:
output_mess += ' - Created %s_%s.pdf\n' % \
- (doc, version)
-
+ (doc, version)
print(output_mess)
print('\n\n'+'~'*72)
--
GitLab