From 2025e70872dcbfa0039ec000ea11d98d34d6cf70 Mon Sep 17 00:00:00 2001
From: japm48 <japm48@users.noreply.github.com>
Date: Tue, 5 May 2020 07:49:06 +0200
Subject: docs: use MathJax for HTML documentation
Fixes #2707.
A full LaTeX installation is no longer required for generating the HTML
docs. Also adds some nice-to-have functionalities accessible via
right-click context menu.
Details:
- SVG backend selected by default.
- MathJax recommends not (ab)using their CDN, so
this adds a local dependency.
- Some spurious doxygen warnings were also removed.
---
docs/doxygen/CMakeLists.txt | 7 +++++++
docs/doxygen/Doxyfile.in | 17 +++++------------
docs/doxygen/other/build_guide.dox.in | 1 +
3 files changed, 13 insertions(+), 12 deletions(-)
(limited to 'docs/doxygen')
diff --git a/docs/doxygen/CMakeLists.txt b/docs/doxygen/CMakeLists.txt
index 91030d0f50..2f0bf35bfa 100644
--- a/docs/doxygen/CMakeLists.txt
+++ b/docs/doxygen/CMakeLists.txt
@@ -18,6 +18,13 @@ set(enable_html_docs YES)
set(enable_latex_docs NO)
set(enable_xml_docs YES)
+if(MATHJAX2_FOUND)
+ set(enable_mathjax YES)
+else()
+ message(WARNING "MathJax 2 not found, HTML equations might not be properly rendered.")
+ set(enable_mathjax NO)
+endif()
+
configure_file(
${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
diff --git a/docs/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in
index ba4e0692f3..09b82eab8a 100644
--- a/docs/doxygen/Doxyfile.in
+++ b/docs/doxygen/Doxyfile.in
@@ -232,13 +232,6 @@ TAB_SIZE = 8
ALIASES =
-# This tag can be used to specify a number of word-keyword mappings (TCL only).
-# A mapping has the form "name=value". For example adding
-# "class=itcl::class" will allow you to use the command class in the
-# itcl::class meaning.
-
-TCL_SUBST =
-
# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
# sources only. Doxygen will then generate output that is more tailored for C.
# For instance, some of the names that are used will be different. The list
@@ -1309,14 +1302,14 @@ FORMULA_TRANSPARENT = YES
# output. When enabled you may also need to install MathJax separately and
# configure the path to it using the MATHJAX_RELPATH option.
-USE_MATHJAX = NO
+USE_MATHJAX = @enable_mathjax@
# When MathJax is enabled you can set the default output format to be used for
# the MathJax output. Supported types are HTML-CSS, NativeMML (i.e. MathML) and
# SVG. The default value is HTML-CSS, which is slower, but has the best
# compatibility.
-MATHJAX_FORMAT = HTML-CSS
+MATHJAX_FORMAT = SVG
# When MathJax is enabled you need to specify the location relative to the
# HTML output directory using the MATHJAX_RELPATH option. The destination
@@ -1328,12 +1321,12 @@ MATHJAX_FORMAT = HTML-CSS
# However, it is strongly recommended to install a local
# copy of MathJax from http://www.mathjax.org before deployment.
-MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
+MATHJAX_RELPATH = @MATHJAX2_PATH@
# The MATHJAX_EXTENSIONS tag can be used to specify one or MathJax extension
# names that should be enabled during MathJax rendering.
-MATHJAX_EXTENSIONS =
+MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
# The MATHJAX_CODEFILE tag can be used to specify a file with javascript
# pieces of code that will be used on startup of the MathJax code.
@@ -1909,7 +1902,7 @@ DIRECTORY_GRAPH = NO
# HTML_FILE_EXTENSION to xhtml in order to make the SVG files
# visible in IE 9+ (other browsers do not have this requirement).
-DOT_IMAGE_FORMAT = png
+DOT_IMAGE_FORMAT = svg
# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
# enable generation of interactive SVG images that allow zooming and panning.
diff --git a/docs/doxygen/other/build_guide.dox.in b/docs/doxygen/other/build_guide.dox.in
index ea5b4851a5..c7e2b9d24c 100644
--- a/docs/doxygen/other/build_guide.dox.in
+++ b/docs/doxygen/other/build_guide.dox.in
@@ -54,6 +54,7 @@ Other compilers may work, but are not supported.
\subsection dep_docs docs: Building the documentation
\li doxygen (>= 1.5) http://www.stack.nl/~dimitri/doxygen/download.html
+\li MathJax (>= 2, <3) https://github.com/mathjax/MathJax-src
\subsection dep_grc grc: The GNU Radio Companion
\li Cheetah (>= 2.0) http://www.cheetahtemplate.org/
--
cgit v1.2.3