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
Anas Nashif
parent
4a2ba0dd04
commit
9945e7fda0
7 changed files with 161 additions and 12 deletions
|
|
@ -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()
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
44
doc/scripts/fix_tex.py
Normal 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()
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue