From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from tama500.ecl.ntt.co.jp (tama500.ecl.ntt.co.jp [129.60.39.148]) by dpdk.org (Postfix) with ESMTP id BA6F81B5E7 for ; Mon, 26 Nov 2018 08:29:40 +0100 (CET) Received: from vc1.ecl.ntt.co.jp (vc1.ecl.ntt.co.jp [129.60.86.153]) by tama500.ecl.ntt.co.jp (8.13.8/8.13.8) with ESMTP id wAQ7TdEC013234; Mon, 26 Nov 2018 16:29:39 +0900 Received: from vc1.ecl.ntt.co.jp (localhost [127.0.0.1]) by vc1.ecl.ntt.co.jp (Postfix) with ESMTP id AB3A4EA8074; Mon, 26 Nov 2018 16:29:39 +0900 (JST) Received: from localhost.localdomain (lobster.nslab.ecl.ntt.co.jp [129.60.13.95]) by vc1.ecl.ntt.co.jp (Postfix) with ESMTP id 9C70BEA7FC3; Mon, 26 Nov 2018 16:29:39 +0900 (JST) From: ogawa.yasufumi@lab.ntt.co.jp To: ferruh.yigit@intel.com, spp@dpdk.org, ogawa.yasufumi@lab.ntt.co.jp Date: Mon, 26 Nov 2018 16:27:26 +0900 Message-Id: <1543217247-13783-2-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1543217247-13783-1-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> References: <1543217247-13783-1-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> X-TM-AS-MML: disable Subject: [spp] [PATCH 1/2] docs: revise doc compilation X-BeenThere: spp@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Soft Patch Panel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 26 Nov 2018 07:29:41 -0000 From: Yasufumi Ogawa * 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 --- 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