doc: add ability to generate PDF

This adds new targets to generate build documentation through
LaTEX to PDF.

There are a few notes:

1. pdflatex complains about the tex file generated by doxygen
   so it needs to be fixed with a Python script before feeding
   in through pdflatex.

2. SVG files are not recognized by pdflatex so they are converted
   to known good format on the fly, only for producing PDF. This
   uses the libRSVG's rsvg-convert tool.

Relates to #6782.

Signed-off-by: Daniel Leung <daniel.leung@intel.com>
This commit is contained in:
Daniel Leung 2018-08-23 11:11:11 -07:00 committed by Anas Nashif
commit 9945e7fda0
7 changed files with 161 additions and 12 deletions

View file

@ -17,6 +17,16 @@ if(${SPHINXBUILD} STREQUAL SPHINXBUILD-NOTFOUND)
message(FATAL_ERROR "The 'sphinx-build' command was not found. Make sure you have Sphinx installed.")
endif()
# Note that this won't force fatal error if latexmk is not found.
# Not having LaTeX tools should not prevent people from generating HTML docs.
find_program(
LATEXMK
latexmk
)
if(${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
message(WARNING "The 'latexmk' command was not found. Targets to build PDF will not be available.")
endif()
if(NOT DEFINED SPHINXOPTS)
set(SPHINXOPTS -q)
else()
@ -24,8 +34,13 @@ else()
endif()
if(NOT DEFINED SPHINX_OUTPUT_DIR)
set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/html
)
set(SPHINX_OUTPUT_DIR_HTML ${CMAKE_CURRENT_BINARY_DIR}/html)
set(SPHINX_OUTPUT_DIR_LATEX ${CMAKE_CURRENT_BINARY_DIR}/latex)
set(SPHINX_OUTPUT_DIR_PDF ${CMAKE_CURRENT_BINARY_DIR}/pdf)
else()
set(SPHINX_OUTPUT_DIR_HTML ${SPHINX_OUTPUT_DIR})
set(SPHINX_OUTPUT_DIR_LATEX ${SPHINX_OUTPUT_DIR})
set(SPHINX_OUTPUT_DIR_PDF ${SPHINX_OUTPUT_DIR})
endif()
if(NOT DEFINED DOC_TAG)
@ -109,13 +124,17 @@ add_custom_target(
)
set(KI_SCRIPT ${ZEPHYR_BASE}/scripts/filter-known-issues.py)
set(FIX_TEX_SCRIPT ${ZEPHYR_BASE}/doc/scripts/fix_tex.py)
set(CONFIG_DIR ${ZEPHYR_BASE}/.known-issues/doc)
#
# HTML section
#
add_custom_target(
html
COMMAND ${CMAKE_COMMAND} -E env
ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b html ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR}
${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b html ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_HTML}
# Merge the Doxygen and Sphinx logs into a single file
COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONFIG_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
@ -123,6 +142,59 @@ add_custom_target(
${SPHINX_USES_TERMINAL}
)
#
# LaTEX section
#
add_custom_target(
latex
COMMAND ${CMAKE_COMMAND} -E env
ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b latex -t svgconvert ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_LATEX}
# Merge the Doxygen and Sphinx logs into a single file
COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONFIG_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
COMMAND ${PYTHON_EXECUTABLE} ${FIX_TEX_SCRIPT} ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
${SPHINX_USES_TERMINAL}
)
#
# PDF section
#
if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
add_custom_command(
OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf
DEPENDS latexdocs ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
COMMAND ${CMAKE_COMMAND} -E env
LATEXOPTS='-halt-on-error -no-shell-escape'
${LATEXMK} -quiet -pdf -dvi- -ps-
WORKING_DIRECTORY ${SPHINX_OUTPUT_DIR_LATEX}
)
if(NOT DEFINED SPHINX_OUTPUT_DIR)
# Although latexmk allows specifying output directory,
# makeindex fails if one is specified.
# Hence the need of this to copy the PDF file over.
add_custom_command(
OUTPUT ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_OUTPUT_DIR_PDF}
COMMAND ${CMAKE_COMMAND} -E copy ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
DEPENDS ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf
)
endif()
add_custom_target(
pdf
DEPENDS ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
${SPHINX_USES_TERMINAL}
)
endif()
#
# Dependencies and final targets
#
add_dependencies(html content doxy kconfig)
add_custom_target(
@ -130,3 +202,18 @@ add_custom_target(
)
add_dependencies(htmldocs html)
add_dependencies(latex content doxy kconfig)
add_custom_target(
latexdocs
)
add_dependencies(latexdocs latex)
if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
add_custom_target(
pdfdocs
)
add_dependencies(pdfdocs pdf)
endif()

View file

@ -44,6 +44,10 @@ extensions = [
'zephyr.application',
]
# Only use SVG converter when it is really needed, e.g. LaTeX.
if tags.has("svgconvert"):
extensions.append('sphinxcontrib.rsvgconverter')
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -263,7 +267,7 @@ latex_elements = {
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
'preamble': '\setcounter{tocdepth}{2}',
# Latex figure (float) alignment
#'figure_align': 'htbp',
@ -297,7 +301,6 @@ latex_documents = [
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples

View file

@ -64,7 +64,8 @@ On Ubuntu host system:
sudo apt-get install --no-install-recommends git cmake ninja-build gperf \
ccache doxygen dfu-util device-tree-compiler \
python3-ply python3-pip python3-setuptools python3-wheel xz-utils file \
make gcc-multilib autoconf automake libtool
make gcc-multilib autoconf automake libtool librsvg2-bin \
texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended
On Fedora host system:
@ -74,14 +75,15 @@ On Fedora host system:
sudo dnf install git cmake ninja-build gperf ccache\
doxygen dfu-util dtc python3-pip \
python3-ply python3-yaml dfu-util dtc python3-pykwalify \
glibc-devel.i686 libstdc++-devel.i686 autoconf automake libtool
glibc-devel.i686 libstdc++-devel.i686 autoconf automake libtool \
texlive-latex latexmk texlive-collection-fontsrecommended librsvg2-tools
On Clear Linux host system:
.. code-block:: console
sudo swupd bundle-add c-basic dev-utils dfu-util dtc \
os-core-dev python-basic python3-basic
os-core-dev python-basic python3-basic texlive
Install additional packages required for development with Zephyr::

View file

@ -89,6 +89,14 @@ To build for the ARM-based Nordic nRF52 Development Kit:
:host-os: unix
:goals: build
Install tools to build Zephyr documentation:
.. code-block:: console
brew install mactex librsvg
tlmgr install latexmk
tlmgr install collection-fontsrecommended
.. _setting_up_mac_toolchain:
Setting Up the Toolchain

View file

@ -39,8 +39,10 @@ Source code for the Zephyr Project is maintained in the Zephyr Project's
.. _GitHub repo: https://github.com/zephyrproject-rtos/zephyr
Sections
********
.. only:: html
Sections
********
.. toctree::
:maxdepth: 1
@ -55,8 +57,10 @@ Sections
devices/index.rst
subsystems/subsystems.rst
Indices and Tables
******************
.. only:: html
Indices and Tables
******************
* :ref:`glossary`

44
doc/scripts/fix_tex.py Normal file
View file

@ -0,0 +1,44 @@
#!/usr/bin/env python3
#
# Copyright (c) 2018, Intel Corporation
#
# SPDX-License-Identifier: Apache-2.0
# Fix the .tex file produced by doxygen
# before feeding to pdflatex or latexmk.
import argparse
import re
def regex_replace(tex_file):
patterns = [
# runaway argument
("}}\r?\n=\r?\n\r?\n\t{6}", "}} = ")
]
f = open(tex_file, mode='r', encoding="utf-8")
content = f.read()
f.close()
for p in patterns:
content = re.sub(p[0], p[1], content)
f = open(tex_file, mode='w', encoding="utf-8")
f.write(content)
f.close()
return
def main():
parser = argparse.ArgumentParser(description='Fix the .tex file produced '
'by doxygen before feeding it to '
'latexmk (or pdflatex).')
parser.add_argument('tex_file', nargs=1)
args = parser.parse_args()
regex_replace(args.tex_file[0])
if __name__ == "__main__":
main()

View file

@ -3,6 +3,7 @@ breathe==4.9.1
sphinx==1.7.5
docutils==0.14
sphinx_rtd_theme
sphinxcontrib-svg2pdfconverter
junit2html
PyYAML==3.12
ply==3.10