[spp] [PATCH 1/2] docs: revise doc compilation

[ogawa.yasufumi@lab.ntt.co.jp]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

* Change to get version with `make showversion` from GNUmakefile for
  passing it to other programs. Not need to define the version in
  several files anymore.

* Simply create PDF images from GNUmakefile instead of using dedicated
  `gen_pdf_imgs.py`.

* Add DPDK's custom style configs to `conf.py` for compiling PDF.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 GNUmakefile                 | 31 +++++++++++++++-------
 docs/guides/conf.py         | 63 ++++++++++++++++++++++++++-------------------
 docs/guides/gen_pdf_imgs.py | 54 --------------------------------------
 3 files changed, 58 insertions(+), 90 deletions(-)
 delete mode 100644 docs/guides/gen_pdf_imgs.py

diff --git a/GNUmakefile b/GNUmakefile
index 1096c47..206a4c6 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -1,12 +1,9 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright(c) 2018 Nippon Telegraph and Telephone Corporation
 
-VERSION = 18.05.1
-
-ifeq ($(RTE_SDK),)
-$(error "Please define RTE_SDK environment variable")
-endif
+VERSION := 18.05.1
 
+ifneq ($(RTE_SDK),)
 # Default target, can be overriden by command line or environment
 RTE_TARGET ?= x86_64-native-linuxapp-gcc
 
@@ -15,20 +12,36 @@ include $(RTE_SDK)/mk/rte.vars.mk
 DIRS-y += src
 
 include $(RTE_SDK)/mk/rte.extsubdir.mk
+endif
 
-DOC_ROOT = docs/guides
+.PHONY: showversion
+showversion:
+	@set -- ;\
+		printf $(VERSION);\
 
 # Compile RST documents
+DOC_ROOT = docs/guides
+
 .PHONY: doc
-doc: doc-pdf doc-html
+doc: doc-all
+doc-all: doc-pdf doc-html
 
 .PHONY: doc-html
 doc-html:
 	make -C $(DOC_ROOT) html
 
+RTE_PDF_DPI := 300
+IMG_DIR := docs/guides/images
+SVGS := $(wildcard $(IMG_DIR)/*.svg)
+SVGS += $(wildcard $(IMG_DIR)/*/*.svg)
+SVGS += $(wildcard $(IMG_DIR)/*/*/*.svg)
+PDFS := $(SVGS:%.svg=%.pdf)
+
+%.pdf: %.svg
+	inkscape -d $(RTE_PDF_DPI) -D -f $< -A $@ $(RTE_INKSCAPE_VERBOSE)
+
 .PHONY: doc-pdf
-doc-pdf:
-	python $(DOC_ROOT)/gen_pdf_imgs.py
+doc-pdf: $(PDFS)
 	make -C $(DOC_ROOT) latexpdf
 	@echo "Succeeded to generate '$(DOC_ROOT)/_build/latex/SoftPatchPanel.pdf'"
 
diff --git a/docs/guides/conf.py b/docs/guides/conf.py
index a2f9c20..7341663 100644
--- a/docs/guides/conf.py
+++ b/docs/guides/conf.py
@@ -1,25 +1,9 @@
-# -*- coding: utf-8 -*-
-#
-# Soft Patch Panel documentation build configuration file, created by
-# sphinx-quickstart on Thu Jan 25 13:52:03 2018.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Nippon Telegraph and Telephone Corporation
 
+import subprocess
+from pygments.formatters.latex import LatexFormatter
+from sphinx.highlighting import PygmentsBridge
 
 # -- General configuration ------------------------------------------------
 
@@ -55,9 +39,9 @@ author = ''
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
-# The short X.Y version.
-version = u'v18.05.1'
+
+version = subprocess.check_output(['make', '-sRrC', '../../', 'showversion'])
+
 # The full version, including alpha/beta/rc tags.
 release = version
 
@@ -121,11 +105,20 @@ htmlhelp_basename = 'SoftPatchPaneldoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
+# Latex directives to be included directly in the latex/pdf docs.
+custom_latex_preamble = r"""
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{helvet}
+\renewcommand{\familydefault}{\sfdefault}
+\RecustomVerbatimEnvironment{Verbatim}{Verbatim}{xleftmargin=5mm}
+"""
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
-    'papersize': 'letterpaper',
-    # 'papersize': 'a4paper',
+    #'papersize': 'letterpaper',
+    'papersize': 'a4paper',
 
     # The font size ('10pt', '11pt' or '12pt').
     #
@@ -137,9 +130,25 @@ latex_elements = {
 
     # Latex figure (float) alignment
     #
-    'figure_align': 'htbp',
+    #'figure_align': 'htbp',
+    # remove blank pages
+    'classoptions': ',openany,oneside',
+    'babel': '\\usepackage[english]{babel}',
+    # customize Latex formatting
+    'preamble': custom_latex_preamble
 }
 
+# Override the default Latex formatter in order to modify the
+# code/verbatim blocks.
+class CustomLatexFormatter(LatexFormatter):
+    def __init__(self, **options):
+        super(CustomLatexFormatter, self).__init__(**options)
+        # Use the second smallest font size for code/verbatim blocks.
+        self.verboptions = r'formatcom=\footnotesize'
+
+# Replace the default latex formatter.
+PygmentsBridge.latex_formatter = CustomLatexFormatter
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
diff --git a/docs/guides/gen_pdf_imgs.py b/docs/guides/gen_pdf_imgs.py
deleted file mode 100644
index 2caf583..0000000
--- a/docs/guides/gen_pdf_imgs.py
+++ /dev/null
@@ -1,54 +0,0 @@
-#!/usr/bin/env python
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright(c) 2018 Nippon Telegraph and Telephone Corporation
-
-# Generate PDF images form SVG to embed targetting PDF document.
-
-import os
-import subprocess
-
-DPI = 300  # resolution for export
-
-
-def filter_list(alist, ext='svg'):
-    """Filter files with given extension"""
-
-    res = []
-    for ent in alist:
-        ent_ext = ent.split('.').pop()
-        if ent_ext == ext:
-            res.append(ent)
-    return res
-
-
-def main():
-    work_dir = os.path.dirname(__file__)
-    if work_dir == '':
-        work_dir = '.'
-
-    img_dir_info = os.walk('%s/images' % work_dir)
-    for root, dirs, files in img_dir_info:
-        if len(files) > 0:
-            svg_files = filter_list(files)
-            for fname in svg_files:
-                # setup inkscape options
-                tmp = fname.split('.')
-                tmp.pop()
-                base_fname = tmp[0]
-                svg_f = base_fname + '.svg'
-                pdf_f = base_fname + '.pdf'
-                svg_fpath = '%s/%s' % (root, svg_f)
-                pdf_fpath = '%s/%s' % (root, pdf_f)
-
-                cmd = 'inkscape -d %d -D -f %s --export-pdf %s' % (
-                    DPI, svg_fpath, pdf_fpath)
-                print(cmd)
-                subprocess.call(cmd, shell=True)
-
-    # Ensure PDF img is generated.
-    while os.path.exists(pdf_fpath) == False:
-        pass
-
-
-if __name__ == "__main__":
-    main()
-- 
2.7.4