Browse Source

PDF generation support with --pdf option

This commit proposes PDF generation with pdflatex.
Executing Sphinx with latex option generates .tex files will
be performed first, and pdflatex converts from .tex to .pdf files.

More details are as followings:

- Adds texlive related package binary dependency (>= Trusty)
  : inkscape texlive-latex-base texlive-latex-extra
    texlive-fonts-recommended
- build-rst.sh: --pdf option is added
- install-guide PDF support using --pdf option
- PDF support for serveral documents
  : arch-design, cli-reference, ha-guide, ops-guide, user-guide,
    networking-guide, arch-design-draft
  (testable using like "tox -e build -- networking-guide --pdf")
- Intermidiate files for building .tex (required for converting into
  .pdf) are stored in "build/pdf" folder.

Change-Id: I66242f44bb13f1a09be0904a491c84f42f25c3a2
Implements: blueprint build-pdf-from-rst-guides
changes/43/396943/9
Ian Y. Choi 5 years ago
parent
commit
4d42034432
  1. 4
      bindep.txt
  2. 25
      tools/build-all-rst.sh
  3. 4
      tools/build-install-guides-rst.sh
  4. 20
      tools/build-rst.sh

4
bindep.txt

@ -19,3 +19,7 @@ python-lxml
xsltproc [platform:dpkg]
zlib-devel [platform:rpm]
zlib1g-dev [platform:dpkg]
inkscape
texlive-latex-base [platform:dpkg]
texlive-latex-extra [platform:dpkg]
texlive-fonts-recommended [platform:dpkg]

25
tools/build-all-rst.sh

@ -9,18 +9,35 @@ if [[ $# > 0 ]] ; then
fi
fi
PDF_OPTION="--pdf"
# PDF targets for Install guides are dealt in build-install-guides-rst.sh
PDF_TARGETS=( 'arch-design' 'arch-design-draft' 'cli-reference'\
'ha-guide' 'networking-guide'\
'ops-guide' 'user-guide' )
for guide in admin-guide arch-design cli-reference contributor-guide \
ha-guide image-guide ops-guide user-guide; do
tools/build-rst.sh doc/$guide --build build \
--target $guide $LINKCHECK
if [[ ${PDF_TARGETS[*]} =~ $guide ]]; then
tools/build-rst.sh doc/$guide --build build \
--target $guide $LINKCHECK $PDF_OPTION
else
tools/build-rst.sh doc/$guide --build build \
--target $guide $LINKCHECK
fi
done
# Draft guides
# This includes guides that we publish from stable branches
# as versioned like the networking-guide.
for guide in networking-guide arch-design-draft config-reference; do
tools/build-rst.sh doc/$guide --build build \
--target "draft/$guide" $LINKCHECK
if [[ ${PDF_TARGETS[*]} =~ $guide ]]; then
tools/build-rst.sh doc/$guide --build build \
--target "draft/$guide" $LINKCHECK $PDF_OPTION
else
tools/build-rst.sh doc/$guide --build build \
--target "draft/$guide" $LINKCHECK
fi
done
tools/build-install-guides-rst.sh $LINKCHECK

4
tools/build-install-guides-rst.sh

@ -27,7 +27,7 @@ for tag in $TAGS; do
# Build the guide with debconf
# To use debian only contents, use "debian" tag.
tools/build-rst.sh doc/install-guide-debconf \
--tag debian --target "draft/install-guide-${tag}" $LINKCHECK
--tag debian --target "draft/install-guide-${tag}" $LINKCHECK --pdf
else
##
# Because Sphinx uses the first heading as title regardless of
@ -40,6 +40,6 @@ for tag in $TAGS; do
# Build the guide
tools/build-rst.sh doc/install-guide \
--tag ${tag} --target "draft/install-guide-${tag}" $LINKCHECK
--tag ${tag} --target "draft/install-guide-${tag}" $LINKCHECK --pdf
fi
done

20
tools/build-rst.sh

@ -21,6 +21,7 @@ if [ -z "$DIRECTORY" ] ; then
echo "--target TARGET: Copy files to publish-docs/$TARGET"
echo "--build BUILD: Name of build directory"
echo "--linkcheck: Check validity of links instead of building"
echo "--pdf: PDF file generation"
exit 1
fi
@ -29,6 +30,7 @@ TAG=""
TAG_OPT=""
BUILD=""
LINKCHECK=""
PDF=""
while [[ $# > 0 ]] ; do
option="$1"
@ -49,6 +51,9 @@ while [[ $# > 0 ]] ; do
TARGET="$2"
shift
;;
--pdf)
PDF=1
;;
esac
shift
done
@ -57,11 +62,14 @@ done
if [ -z "$BUILD" ] ; then
if [ -z "$TAG" ] ; then
BUILD_DIR="$DIRECTORY/build/html"
BUILD_DIR_PDF="$DIRECTORY/build/pdf"
else
BUILD_DIR="$DIRECTORY/build-${TAG}/html"
BUILD_DIR_PDF="$DIRECTORY/build-${TAG}/pdf"
fi
else
BUILD_DIR="$DIRECTORY/$BUILD/html"
BUILD_DIR_PDF="$DIRECTORY/$BUILD/pdf"
fi
DOCTREES="${BUILD_DIR}.doctrees"
@ -85,7 +93,17 @@ else
$TAG_OPT $DIRECTORY/source $BUILD_DIR
set +x
# Copy RST
# PDF generation
if [ "$PDF" = "1" ] ; then
set -x
sphinx-build -E -W -d $DOCTREES -b latex \
$TAG_OPT $DIRECTORY/source $BUILD_DIR_PDF
make -C $BUILD_DIR_PDF
cp $BUILD_DIR_PDF/*.pdf $BUILD_DIR/
set +x
fi
# Copy RST (and PDF)
if [ "$TARGET" != "" ] ; then
mkdir -p publish-docs/$TARGET
rsync -a $BUILD_DIR/ publish-docs/$TARGET/

Loading…
Cancel
Save