From db677f1bab18bbcb086af7dfa9c84c12c26fd6c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Villemot?= Date: Fri, 15 Sep 2023 18:14:17 +0200 Subject: [PATCH] Meson build system: add documentation --- meson.build | 112 ++++++++++++++++++++++++++++++- preprocessor | 2 +- scripts/sphinx-build-pdf-wrapper | 27 ++++++++ 3 files changed, 138 insertions(+), 3 deletions(-) create mode 100755 scripts/sphinx-build-pdf-wrapper diff --git a/meson.build b/meson.build index 49e695c56..1eef8a796 100644 --- a/meson.build +++ b/meson.build @@ -1,6 +1,5 @@ # TODO: # - Add tests that are individually listed in {M,O}_TRS_FILES of tests/Makefile.am -# - Build documentation # - Install files in right location # - with -Dprefer_static=true, under Octave/Windows, we are now linking the compiler libs (libgcc, libstdc++, libgfortran, libquadmath, libssp, libgomp) statically (contrary to what we were doing with autotools). In theory this is better, because the compiler used for creating the Octave binary may be different from the one used for creating our MEX. Check that this is ok # - configuration option to disable documentation @@ -29,7 +28,6 @@ c_compiler = meson.get_compiler('c') ### Preprocessor subdir('preprocessor/src') -subdir('preprocessor/doc') ### Generated M-file @@ -475,6 +473,116 @@ ms_sbvar_command_line_src = [ 'contrib/ms-sbvar/switch_dw/switching/dw_switch_op shared_module('ms_sbvar_command_line', ms_sbvar_command_line_src, kwargs : mex_ms_sbvar_kwargs, dependencies : [ gsl_dep, matio_dep ]) +### Documentation + +## Reference manual + +sphinx_build_exe = find_program('sphinx-build') + +sphinx_src = [ 'doc/manual/source/conf.py', + 'doc/manual/source/time-series.rst', + 'doc/manual/source/the-configuration-file.rst', + 'doc/manual/source/index.rst', + 'doc/manual/source/dynare-misc-commands.rst', + 'doc/manual/source/bibliography.rst', + 'doc/manual/source/running-dynare.rst', + 'doc/manual/source/the-model-file.rst', + 'doc/manual/source/introduction.rst', + 'doc/manual/source/reporting.rst', + 'doc/manual/source/examples.rst', + 'doc/manual/source/installation-and-configuration.rst', + 'doc/manual/source/_templates/about.html', + 'doc/manual/source/_templates/navigation.html', + 'doc/manual/source/_static/dlogo.svg', + 'doc/manual/source/_static/custom.css', + 'doc/manual/source/_static/report.png', + 'doc/manual/utils/dynare_dom.py', + 'doc/manual/utils/dynare_lex.py' ] + +sphinx_defines = [ '-D', 'release=' + meson.project_version(), + '-D', 'version=' + meson.project_version() ] + +custom_target('dynare-manual.html', output : 'dynare-manual.html', input : sphinx_src, + command : [ sphinx_build_exe, '-b', 'html', sphinx_defines, '-d', '@PRIVATE_DIR@', + meson.current_source_dir() / 'doc/manual/source', '@OUTPUT@' ], + install : true, install_dir : 'share/doc/dynare') + +# For the PDF, we are forced to use a wrapper around sphinx-build, because +# the PDF is created in a subdirectory, and meson does not provide an easy way to +# do this. See https://github.com/mesonbuild/meson/discussions/10488 +custom_target('dynare-manual.pdf', output : 'dynare-manual.pdf', input : sphinx_src, + command : [ 'scripts/sphinx-build-pdf-wrapper', sphinx_build_exe.full_path(), + meson.current_source_dir() / 'doc/manual/source', + '@OUTPUT@', '@PRIVATE_DIR@', sphinx_defines ], + install : true, install_dir : 'share/doc/dynare') + +## Various PDFs + +# The following defines the latexmk_exe and latexmk_command variables +subdir('preprocessor/doc') + +custom_target('guide.pdf', output : 'guide.pdf', input : 'doc/guide.tex', + command : latexmk_command, + install : true, install_dir : 'share/doc/dynare') + +custom_target('bvar-a-la-sims.pdf', output : 'bvar-a-la-sims.pdf', input : 'doc/bvar-a-la-sims.tex', + command : latexmk_command, + install : true, install_dir : 'share/doc/dynare') + +custom_target('dr.pdf', output : 'dr.pdf', input : 'doc/dr.tex', + command : latexmk_command, + env : { 'BIBINPUTS': meson.current_source_dir() / 'doc' }, + depend_files : 'doc/dr.bib', + install : true, install_dir : 'share/doc/dynare') + +custom_target('sylvester.pdf', output : 'sylvester.pdf', input : 'doc/sylvester.tex', + command : latexmk_command, + install : true, install_dir : 'share/doc/dynare') + +custom_target('tl.pdf', output : 'tl.pdf', input : 'doc/tl.tex', + command : latexmk_command, + install : true, install_dir : 'share/doc/dynare') + +custom_target('parallel.pdf', output : 'parallel.pdf', input : 'doc/parallel/parallel.tex', + command : latexmk_command, + env : { 'TEXINPUTS': meson.current_source_dir() + '/doc/parallel:', + 'BIBINPUTS': meson.current_source_dir() / 'doc/parallel' }, + depend_files : [ 'doc/parallel/marco.bib', + 'doc/parallel/AvenueParadigm.pdf', + 'doc/parallel/iVaNo_gain.pdf', + 'doc/parallel/iVaNo_time_comp.pdf', + 'doc/parallel/netbook_complete_comp.pdf', + 'doc/parallel/netbook_complete_openclose.pdf', + 'doc/parallel/netbook_partial_comp.pdf', + 'doc/parallel/netbook_partial_openclose.pdf', + 'doc/parallel/quest_complete_comp.pdf', + 'doc/parallel/quest_complete_openclose.pdf', + 'doc/parallel/quest_partial_comp.pdf', + 'doc/parallel/quest_partial_openclose.pdf', + 'doc/parallel/RWMH_quest1_PriorsAndPosteriors1Comp.pdf', + 'doc/parallel/RWMH_quest1_PriorsAndPosteriors2Comp.pdf', + 'doc/parallel/RWMH_quest1_PriorsAndPosteriors3Comp.pdf', + 'doc/parallel/RWMH_quest1_PriorsAndPosteriors4Comp.pdf', + 'doc/parallel/RWMH_quest1_PriorsAndPosteriors5Comp.pdf', + 'doc/parallel/RWMH_quest1_PriorsAndPosteriors6Comp.pdf', + 'doc/parallel/RWMH_quest1_PriorsAndPosteriors7Comp.pdf', + 'doc/parallel/waitbars1.pdf', + 'doc/parallel/waitbars2.pdf', + 'doc/parallel/waitbarsP.pdf' ], + install : true, install_dir : 'share/doc/dynare') + +custom_target('gsa.pdf', output : 'gsa.pdf', input : 'doc/gsa/gsa.tex', + command : latexmk_command, + env : { 'BIBINPUTS': meson.current_source_dir() / 'doc/gsa' }, + depend_files : 'doc/gsa/marco.bib', + install : true, install_dir : 'share/doc/dynare') + +custom_target('dseriesReporting.pdf', output : 'dseriesReporting.pdf', + input : 'doc/dseries-and-reporting/dseriesReporting.tex', + command : latexmk_command, + install : true, install_dir : 'share/doc/dynare') + + ### Tests implemented as .mod or .m (both integration and unit tests) mod_and_m_tests = [ diff --git a/preprocessor b/preprocessor index 6fde1b059..e8dc83e1e 160000 --- a/preprocessor +++ b/preprocessor @@ -1 +1 @@ -Subproject commit 6fde1b05981ba3351ae8662121111bb89bcf6882 +Subproject commit e8dc83e1e7768b324b942aaaed32a533dd69b6c7 diff --git a/scripts/sphinx-build-pdf-wrapper b/scripts/sphinx-build-pdf-wrapper new file mode 100755 index 000000000..4aee4fd41 --- /dev/null +++ b/scripts/sphinx-build-pdf-wrapper @@ -0,0 +1,27 @@ +#!/bin/bash + +set -e + +if (($# < 4 )); then + echo "Usage: $0 sphinx_build_exe source_dir pdf_output private_dir [extra_sphinx_options]" 2>&1 + exit 1 +fi + +sphinx_build_exe=$1 +source_dir=$2 +pdf_output=$3 +private_dir=$4 +shift 4 + +# NB: Ideally we would have called “sphinx-build -M latexpdf” (to combine the +# LaTeX creation and the PDF creation into a single step) but this breaks when +# -D options are passed, presumably due to a bug in sphinx-build. +# See: https://bugs.debian.org/933347 + +"$sphinx_build_exe" -b latex "$@" "$source_dir" "$private_dir" + +make -C "$private_dir" all-pdf + +pdf_basename=${pdf_output##*/} + +mv "$private_dir"/"$pdf_basename" "$pdf_output"