From 437cbf05ad3c56faeccdf02e4b6864eb418292f7 Mon Sep 17 00:00:00 2001 From: Nicolas Bock Date: Mon, 26 Aug 2019 13:41:01 -0600 Subject: [PATCH] Add pdf-docs env to tox.ini - Enable PDF documentation. Based on [1]. - Enable table of contents generation for pdf - Removed literalinclude of designate.conf [2] - Removed illegal character (a literal ESC) - Fix incorrect column count in backends summary section - Replace nodes.line() with nodes.paragraph() [1] https://review.opendev.org/601659 [2] https://github.com/sphinx-doc/sphinx/issues/3099 Change-Id: Ie454f8f9ebc8e36347ce33b22f2e6da0257fe4e0 Signed-off-by: Nicolas Bock --- doc/ext/support_matrix.py | 12 +++++------- doc/source/admin/samples/config.rst | 11 +++++++++-- doc/source/conf.py | 22 +++++++++++++--------- doc/source/contributor/gmr.rst | 8 ++++---- tox.ini | 9 +++++++++ 5 files changed, 40 insertions(+), 22 deletions(-) diff --git a/doc/ext/support_matrix.py b/doc/ext/support_matrix.py index e160689b6..847970f63 100644 --- a/doc/ext/support_matrix.py +++ b/doc/ext/support_matrix.py @@ -271,11 +271,10 @@ class SupportMatrixDirective(rst.Directive): def _build_backend_detail(self, matrix, content): detailstitle = nodes.subtitle(text="Backend Details") - content.append(detailstitle) + content.append(nodes.paragraph()) for key in six.iterkeys(matrix.backends): - content.append( nodes.subtitle(text=matrix.backends[key].title)) content.append( @@ -283,7 +282,7 @@ class SupportMatrixDirective(rst.Directive): matrix.backends[key], matrix)) - content.append(nodes.line()) + content.append(nodes.paragraph()) return content @@ -343,13 +342,11 @@ class SupportMatrixDirective(rst.Directive): summary = nodes.table() summary.set_class("table") summary.set_class("table-condensed") - cols = len(list(six.iterkeys(matrix.backends))) - cols += 2 - summarygroup = nodes.tgroup(cols=cols) + summarygroup = nodes.tgroup(cols=5) summarybody = nodes.tbody() summaryhead = nodes.thead() - for i in range(cols): + for i in range(5): summarygroup.append(nodes.colspec(colwidth=1)) summarygroup.append(summaryhead) summarygroup.append(summarybody) @@ -377,6 +374,7 @@ class SupportMatrixDirective(rst.Directive): blank = nodes.entry() blank.append(nodes.strong(text="Notes")) header.append(blank) + summaryhead.append(header) grades = matrix.grades diff --git a/doc/source/admin/samples/config.rst b/doc/source/admin/samples/config.rst index adfbb8fa9..718e4ab92 100644 --- a/doc/source/admin/samples/config.rst +++ b/doc/source/admin/samples/config.rst @@ -2,5 +2,12 @@ designate.conf ============== -.. literalinclude:: ../../_static/designate.conf.sample - :language: ini +.. only:: html + + .. literalinclude:: ../../_static/designate.conf.sample + :language: ini + +.. only:: latex + + Please refer to the online version of this documentation for a full + config file example. diff --git a/doc/source/conf.py b/doc/source/conf.py index feb1111b9..25379905d 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -201,21 +201,23 @@ htmlhelp_basename = 'designatedoc' # -- Options for LaTeX output -------------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', -# Additional stuff for the LaTeX preamble. -#'preamble': '', + # Additional stuff for the LaTeX preamble. + #'preamble': '', + + 'preamble': r'\setcounter{tocdepth}{3}', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'designate.tex', u'Designate Documentation', - u'Managed I.T.', 'manual'), + ('index', 'doc-designate.tex', u'Designate Documentation', + u'Designate Developers', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -236,8 +238,10 @@ latex_documents = [ #latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +latex_domain_indices = False +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +latex_use_xindy = False # -- Options for manual page output -------------------------------------------- diff --git a/doc/source/contributor/gmr.rst b/doc/source/contributor/gmr.rst index 7549f517b..49185a942 100644 --- a/doc/source/contributor/gmr.rst +++ b/doc/source/contributor/gmr.rst @@ -333,10 +333,10 @@ GMR Example log-dir = /opt/stack/logs/designate log-file = None log-format = None - logging_context_format_string = %(asctime)s.%(msecs)03d %(color)s%(levelname)s %(name)s [%(request_id)s %(user)s %(tenant)s%(color)s] %(instance)s%(color)s%(message)s - logging_debug_format_suffix = from (pid=%(process)d) %(funcName)s %(pathname)s:%(lineno)d - logging_default_format_string = %(asctime)s.%(msecs)03d %(color)s%(levelname)s %(name)s [-%(color)s] %(instance)s%(color)s%(message)s - logging_exception_prefix = %(color)s%(asctime)s.%(msecs)03d TRACE %(name)s %(instance)s + logging_context_format_string = %(asctime)s.%(msecs)03d %(color)s%(levelname)s %(name)s [[01;36m%(request_id)s [00;36m%(user)s %(tenant)s%(color)s] [01;35m%(instance)s%(color)s%(message)s[00m + logging_debug_format_suffix = [00;33mfrom (pid=%(process)d) %(funcName)s %(pathname)s:%(lineno)d[00m + logging_default_format_string = %(asctime)s.%(msecs)03d %(color)s%(levelname)s %(name)s [[00;36m-%(color)s] [01;35m%(instance)s%(color)s%(message)s[00m + logging_exception_prefix = %(color)s%(asctime)s.%(msecs)03d TRACE %(name)s [01;35m%(instance)s[00m mdns-topic = mdns network_api = neutron notification_driver = diff --git a/tox.ini b/tox.ini index cc9dc0161..2cc71e811 100644 --- a/tox.ini +++ b/tox.ini @@ -65,6 +65,15 @@ commands = rm -rf doc/build sphinx-build -W -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 + [testenv:cover] basepython = python3 setenv =