* [spp] [PATCH 1/2] docs: revise doc compilation
2018-11-26 7:27 [spp] [PATCH 0/2] Update docs compilation ogawa.yasufumi
@ 2018-11-26 7:27 ` ogawa.yasufumi
2018-11-26 7:27 ` [spp] [PATCH 2/2] docs: add link to the latest documentation ogawa.yasufumi
1 sibling, 0 replies; 3+ messages in thread
From: ogawa.yasufumi @ 2018-11-26 7:27 UTC (permalink / raw)
To: ferruh.yigit, spp, 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
^ permalink raw reply [flat|nested] 3+ messages in thread