[spp] [PATCH 0/2] Update docs compilation

[spp] [PATCH 0/2] Update docs compilation

[ogawa.yasufumi]

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

Compile of docs has things to be fixed or revised. This series of
patches is to update for the issues.

* Comple of PDF documentation is sometimes failed to embed images
  because latex is launched before creating images with inkscape.

* Version number is defined in Makefile and `conf.py`, and both of them
  are changed if SPP is updated.

Yasufumi Ogawa (2):
  docs: revise doc compilation
  docs: add link to the latest documentation

 GNUmakefile                 | 31 +++++++++++++++-------
 docs/guides/conf.py         | 63 ++++++++++++++++++++++++++-------------------
 docs/guides/gen_pdf_imgs.py | 54 --------------------------------------
 docs/guides/index.rst       |  7 +++++
 4 files changed, 65 insertions(+), 90 deletions(-)
 delete mode 100644 docs/guides/gen_pdf_imgs.py

-- 
2.7.4

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

[ogawa.yasufumi]

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

[spp] [PATCH 2/2] docs: add link to the latest documentation

[ogawa.yasufumi]

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

SPP documentation hosted on dpdk.org is the latest tagged version and
not including the latest topics of developing version. This update is
to add link to the developing version of documentation[1].

[1] https://spp.readthedocs.io/en/latest/

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/index.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/guides/index.rst b/docs/guides/index.rst
index 76c8c79..a01c959 100644
--- a/docs/guides/index.rst
+++ b/docs/guides/index.rst
@@ -13,3 +13,10 @@ SPP documentation
    tools/index
    spp_vf/index
    spp-ctl/index
+
+This documentation is the latest tagged version, but some of the latest
+developing features might be not included.
+All of features not included in this documentation is described in the
+developing version of
+`SPP documentation
+<https://spp.readthedocs.io/en/latest/>`_.
-- 
2.7.4