From 942a245af6cea7de2c056ad1fe6178b61a812908 Mon Sep 17 00:00:00 2001
From: Dmitriy Rabotyagov <drabotyagov@vexxhost.com>
Date: Fri, 18 Oct 2019 17:32:17 +0300
Subject: [PATCH] PDF Documentation Build tox target
This patch adds a `pdf-docs` tox target that will build
PDF versions of our docs. As per the Train community goal:
https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation.html
Add sphinxcontrib-svg2pdfconverter to doc/requirements.txt
to convert our SVGs.
Change-Id: I8783737c2fdfd625e9f015a3630d664e2e2e0cc6
Story: 2006105
---
doc/requirements.txt | 3 ++-
doc/source/_static/.gitkeep | 0
doc/source/conf.py | 19 +++++++++++++++----
tox.ini | 12 +++++++++++-
4 files changed, 28 insertions(+), 6 deletions(-)
create mode 100644 doc/source/_static/.gitkeep
diff --git a/doc/requirements.txt b/doc/requirements.txt
index a4fd1738..a78d3863 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -10,7 +10,8 @@
# automatically be proposed to all the repositories which use it.
sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD
-sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD
+sphinx>=1.8.0,!=2.1.0,>=1.6.2;python_version>='3.4' # BSD
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
openstackdocstheme>=1.20.0 # Apache-2.0
reno>=2.5.0 # Apache-2.0
doc8>=0.6.0 # Apache-2.0
diff --git a/doc/source/_static/.gitkeep b/doc/source/_static/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 9904104a..ebed9765 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -38,6 +38,7 @@
extensions = [
'openstackdocstheme',
'sphinx.ext.autodoc',
+ 'sphinxcontrib.rsvgconverter',
]
# Add any paths that contain templates here, relative to this directory.
@@ -62,11 +63,11 @@ description = 'OpenStack-Ansible deploys OpenStack environments using Ansible.'
project = 'OpenStack-Ansible'
role_name = 'os_octavia'
target_name = 'openstack-ansible-' + role_name
-title = 'OpenStack-Ansible Documentation: ' + role_name + 'role'
+title = 'OpenStack-Ansible Documentation: ' + role_name + ' role'
# The link to the browsable source code (for the left hand menu)
oslosphinx_cgit_link = (
- "https://git.openstack.org/cgit/openstack/{}".format(target_name)
+ "https://opendev.org/openstack/{}".format(target_name)
)
# openstackdocstheme options
@@ -219,10 +220,12 @@ htmlhelp_basename = target_name + '-docs'
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- (master_doc, target_name + '.tex',
- title, author, 'manual'),
+ (master_doc, 'doc-' + target_name + '.tex',
+ title.replace("_", "\_"), author, 'manual'),
]
+latex_use_xindy = False
+
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
@@ -279,3 +282,11 @@ texinfo_documents = [
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False
+# -- Options for PDF output --------------------------------------------------
+
+pdf_documents = [
+ (master_doc, target_name,
+ title, author)
+]
+
+locale_dirs = ['locale/']
diff --git a/tox.ini b/tox.ini
index c421c2b7..667cca76 100644
--- a/tox.ini
+++ b/tox.ini
@@ -35,11 +35,21 @@ setenv =
[testenv:docs]
basepython = python3
deps = -r{toxinidir}/doc/requirements.txt
-commands=
+commands =
bash -c "rm -rf doc/build"
sphinx-build -b html doc/source doc/build/html
+[testenv:pdf-docs]
+basepython = python3
+deps = {[testenv:docs]deps}
+whitelist_externals =
+ make
+commands =
+ sphinx-build -W -b latex doc/source doc/build/pdf
+ make -C doc/build/pdf
+
+
[doc8]
# Settings for doc8:
extensions = .rst