Integrate new reference manual

- integrate with autoconf/automake, so that "make html pdf" now build the
  manual
- remove the old texinfo manual
- the PDF manual is now called dynare-manual.pdf (Closes #1543)
- add a Gitlab CI job that updates the online unstable manual under
  www.dynare.org/manual-unstable/
parent 790c5661
......@@ -56,12 +56,8 @@ checksum
*.bbl
*.blg
*.lof
/doc/dynare.html
/doc/dynare.info*
/doc/texinfo.tex
/doc/version.texi
/doc/mdate-sh
/doc/stamp-vti
/doc/manual/build
/doc/manual/utils/version.py
!/doc/guide.bbl
!/doc/parallel/AvenueParadigm.pdf
!/doc/parallel/iVaNo_*.pdf
......
......@@ -32,12 +32,10 @@ build_doc:
script:
- autoreconf -si
- ./configure --disable-matlab --disable-octave
- make -j $(nproc) info pdf html
- make -j $(nproc) pdf html
artifacts:
paths:
- doc/dynare.info*
- doc/dynare.html
- doc/dynare.pdf
- doc/manual/build/
testsuite_matlab:
stage: test
......@@ -105,3 +103,16 @@ test_dynare++:
- make -C dynare++ check
dependencies:
- build_binaries
deploy_manual_unstable:
stage: deploy
only:
- master@Dynare/dynare
tags:
- secure
dependencies:
- build_doc
script:
- rm -rf doc/manual/build/html/_static/mathjax
- ln -s /usr/share/javascript/mathjax doc/manual/build/html/_static/mathjax
- rsync --recursive --links --delete --compress doc/manual/build/html/ dynbot@eris.dynare.org:/srv/www.dynare.org/manual-unstable/
......@@ -77,9 +77,9 @@ A number of tools and libraries are needed in order to recompile everything. You
- A decent LaTeX distribution (if you want to compile PDF documentation),
ideally with Beamer
- For building the reference manual:
- [GNU Texinfo](http://www.gnu.org/software/texinfo/)
- [Latex2HTML](http://www.latex2html.org), if you want nice mathematical formulas in HTML output
- [Doxygen](http://www.stack.nl/%7Edimitri/doxygen/) (if you want to build Dynare preprocessor source documentation)
- [Sphinx](http://www.sphinx-doc.org/)
- [MathJax](https://www.mathjax.org/)
- [Doxygen](http://www.stack.nl/%7Edimitri/doxygen/) (if you want to build Dynare preprocessor source documentation)
- For Octave, the development libraries corresponding to the UMFPACK packaged with Octave
### Preparing the sources
......@@ -217,14 +217,14 @@ All the prerequisites are packaged:
- `texlive-fonts-extra` (for ccicons)
- `texlive-latex-recommended`
- `texlive-science` (for amstex)
- `texinfo`
- `lmodern` (for macroprocessor PDF)
- `latex2html`
- `python3-sphinx`
- `libjs-mathjax`
- `doxygen`
You can install them all at once with:
```
apt install build-essential gfortran liboctave-dev libboost-graph-dev libboost-filesystem-dev libgsl-dev libmatio-dev libslicot-dev libslicot-pic libsuitesparse-dev flex bison autoconf automake texlive texlive-publishers texlive-extra-utils texlive-formats-extra texlive-latex-extra texlive-fonts-extra texlive-latex-recommended texlive-science texinfo lmodern latex2html doxygen
apt install build-essential gfortran liboctave-dev libboost-graph-dev libboost-filesystem-dev libgsl-dev libmatio-dev libslicot-dev libslicot-pic libsuitesparse-dev flex bison autoconf automake texlive texlive-publishers texlive-extra-utils texlive-formats-extra texlive-latex-extra texlive-fonts-extra texlive-latex-recommended texlive-science lmodern doxygen
```
## Windows
......
......@@ -71,16 +71,14 @@ AX_CXX11_THREAD
AX_MATIO
AM_CONDITIONAL([HAVE_MATIO], [test "x$has_matio" = "xyes"])
AC_CHECK_PROG([MAKEINFO], [makeinfo], [makeinfo])
AC_CHECK_PROG([PDFLATEX], [pdflatex], [pdflatex])
AM_CONDITIONAL([HAVE_PDFLATEX], [test "x$PDFLATEX" != "x"])
AC_CHECK_PROG([BIBTEX], [bibtex], [bibtex])
AM_CONDITIONAL([HAVE_BIBTEX], [test "x$BIBTEX" != "x"])
AC_CHECK_PROG([LATEX2HTML], [latex2html], [latex2html])
AM_CONDITIONAL([HAVE_LATEX2HTML], [test "x$LATEX2HTML" != "x"])
AC_CHECK_PROG([SPHINXBUILD], [sphinx-build], [sphinx-build])
AM_CONDITIONAL([HAVE_SPHINXBUILD], [test "x$SPHINXBUILD" != "x"])
if test "x$PDFLATEX" != "x" -a "x$BIBTEX" != "x"; then
AX_LATEX_CLASS([beamer], [ax_latex_have_beamer])
......@@ -107,6 +105,8 @@ AM_CONDITIONAL([HAVE_LAPACK], [test x"$ax_lapack_ok" = "xyes"])
AC_CONFIG_FILES([Makefile
VERSION
doc/Makefile
doc/manual/Makefile
doc/manual/utils/version.py
doc/parallel/Makefile
doc/internals/Makefile
doc/gsa/Makefile
......@@ -187,18 +187,12 @@ else
BUILD_DYNARE_INTERNAL_DOC="no (Org export not enabled)"
fi
if test "x$MAKEINFO" != "x"; then
BUILD_DYNARE_INFO="yes"
if test "x$LATEX2HTML" != "x"; then
BUILD_DYNARE_HTML_MANUAL="yes"
else
BUILD_DYNARE_HTML_MANUAL="yes (but with ugly math formulas, missing latex2html)"
fi
if test "x$SPHINXBUILD" != "x"; then
BUILD_DYNARE_HTML_MANUAL="yes"
BUILD_DYNARE_PDF_MANUAL="yes"
else
BUILD_DYNARE_INFO="no (missing makeinfo)"
BUILD_DYNARE_HTML_MANUAL="no (missing makeinfo)"
BUILD_DYNARE_PDF_MANUAL="no (missing makeinfo)"
BUILD_DYNARE_HTML_MANUAL="no (missing sphinx-build)"
BUILD_DYNARE_PDF_MANUAL="no (missing sphinx-build)"
fi
if test "x$OCTAVE" != "x"; then
......@@ -229,8 +223,6 @@ HTML documentation (with "make html"):
Dynare reference manual: $BUILD_DYNARE_HTML_MANUAL
Dynare internal doc: $BUILD_DYNARE_INTERNAL_DOC
Info documentation (with "make info"): $BUILD_DYNARE_INFO
Testsuites (run with "make check"):
Dynare for Octave: $TESTSUITE_OCTAVE
Dynare++: $TESTSUITE_DYNAREPLUSPLUS
......
SUBDIRS = parallel internals gsa dseries-and-reporting
info_TEXINFOS = dynare.texi
if HAVE_LATEX2HTML
html-local: dynare.html
# The temporary directory for latex2html (L2H_TMP) must not contain a dot, so
# enforce standard tmp directory instead of defaulting to current directory
dynare.html: dynare.texi
rm -rf dynare.html
texi2any --html --split=section -c L2H=1 -c L2H_TMP=$${TMPDIR:-/tmp} -c PREFIX=dynare.html dynare.texi
if HAVE_SPHINXBUILD
SUBDIRS += manual
endif
PDF_TARGETS =
......
This diff is collapsed.
# Copyright (C) 2018-2019 Dynare Team
#
# This file is part of Dynare.
#
# Dynare is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Dynare is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Dynare. If not, see <http://www.gnu.org/licenses/>.
SRC = $(wildcard src/source/*.rst)
.PHONY: all html pdf
all: html pdf
html: src/build/html/index.html
src/build/html/index.html: $(SRC) src/source/conf.py
make -C src html
rm -rf src/build/html/_static/mathjax
ln -s /usr/share/javascript/mathjax src/build/html/_static/mathjax
pdf: src/build/latex/dynare.pdf
src/build/latex/dynare.pdf: $(SRC) src/source/conf.py
make -C src latexpdf
push: html
rsync -avz src/build/html/* $(TARGET)
# Dynare reference manual
Source for the Dynare's reference manual which is available at
<http://www.dynare.org/manual-unstable>. The documentation is obtained
using [Sphinx](http://www.sphinx-doc.org/) Pyhthon Documentation
Generator. To build the `html` version of the reference manual just type:
```bash
~$ make html
```
on the command line. The reference manual will be available under
`src/build/html`, provided all the following (debian package)
requirements are met:
- python3,
- python3-sphinx,
- python3-recommonmark, and
- libjs-mathjax
......@@ -20,7 +20,7 @@
import os
import sys
sys.path.insert(0, os.path.abspath('../../utils'))
sys.path.insert(0, os.path.abspath('../utils'))
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.mathjax']
......@@ -41,8 +41,9 @@ author = u'Dynare Team'
add_function_parentheses = False
version = u'4.6-unstable'
release = u'4.6-unstable'
# See ../utils/version.py, which is generated by autoconf
from version import version
from version import release
language = 'en'
......@@ -79,7 +80,7 @@ latex_elements = {
}
latex_documents = [
(master_doc, 'dynare.tex', u'Dynare Reference Manual',
(master_doc, 'dynare-manual.tex', u'Dynare Reference Manual',
u'Dynare team', 'manual'),
]
......
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = Test
SOURCEDIR = source
BUILDDIR = build
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile clean
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
clean:
rm -rf build
......@@ -195,7 +195,7 @@ Files: matlab/utilities/graphics/colorspace.m
Copyright: 2005-2010 Pascal Getreuer
License: BSD-2-clause
Files: doc/dynare.texi doc/*.tex doc/*.svg doc/*.pdf doc/*.bib
Files: doc/*.rst doc/*.tex doc/*.svg doc/*.pdf doc/*.bib
Copyright: 1996-2019 Dynare Team
License: GFDL-NIV-1.3+
......
......@@ -140,10 +140,10 @@ SectionEnd
Section "Documentation and examples (Dynare and Dynare++)"
SetOutPath $INSTDIR\doc
File ..\doc\dynare.pdf ..\doc\guide.pdf ..\doc\bvar-a-la-sims.pdf ..\doc\dr.pdf ..\doc\macroprocessor\macroprocessor.pdf ..\doc\preprocessor\preprocessor.pdf ..\doc\parallel\parallel.pdf ..\doc\gsa\gsa.pdf ..\doc\dseries-and-reporting\dseriesReporting.pdf
File ..\doc\manual\dynare-manual.pdf ..\doc\guide.pdf ..\doc\bvar-a-la-sims.pdf ..\doc\dr.pdf ..\doc\macroprocessor\macroprocessor.pdf ..\doc\preprocessor\preprocessor.pdf ..\doc\parallel\parallel.pdf ..\doc\gsa\gsa.pdf ..\doc\dseries-and-reporting\dseriesReporting.pdf
SetOutPath $INSTDIR\doc\dynare.html
File ..\doc\dynare.html\*.html ..\doc\dynare.html\*.png
SetOutPath $INSTDIR\doc\dynare-manual.html
File /r ..\doc\manual\build\html\*
SetOutPath $INSTDIR\doc\dynare++
File ..\dynare++\doc\dynare++-tutorial.pdf ..\dynare++\doc\dynare++-ramsey.pdf ..\dynare++\sylv\sylvester.pdf ..\dynare++\tl\tl.pdf
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment