From fd0e762d18d6972a4146aa39b4486f29c177d787 Mon Sep 17 00:00:00 2001
From: Markus Zolliker <markus.zolliker@psi.ch>
Date: Wed, 25 Oct 2023 13:24:39 +0200
Subject: [PATCH] doc: drop latex support, add pdf support

latexpdf fails with error message "Too deply nested".
We want to avoid reducing the nesting level of doc strings
in frappy.lib.classdoc (less nice output) or a level of
nesting in method doc strings.

- latex removed from Jenkinsfile
- added support for rst2pdf

Change-Id: Ieb3355ef506e636e7e43a726c68327e3b1154469
Reviewed-on: https://forge.frm2.tum.de/review/c/secop/frappy/+/32406
Tested-by: Jenkins Automated Tests <pedersen+jenkins@frm2.tum.de>
Reviewed-by: Enrico Faulhaber <enrico.faulhaber@frm2.tum.de>
Reviewed-by: Markus Zolliker <markus.zolliker@psi.ch>
---
 ci/Jenkinsfile       | 11 ++++++
 doc/source/conf.py   | 81 +++++++++++++++++++++++++++++++++++++++++++-
 requirements-dev.txt |  1 +
 3 files changed, 92 insertions(+), 1 deletion(-)

diff --git a/ci/Jenkinsfile b/ci/Jenkinsfile
index 06c4366..8b145c6 100644
--- a/ci/Jenkinsfile
+++ b/ci/Jenkinsfile
@@ -141,12 +141,23 @@ def run_docs() {
         '''
     }
 
+    /* does not work with too many quote levels
+     * alternatively use pdf (based on rst2pdf)
+     * or singlehtml converted to pdf manually from a browser (may produce nicer output)
     stage('build latexpdf') {
         sh '''
         . /home/jenkins/secopvenv/bin/activate
         make -C doc latexpdf
         '''
     }
+    */
+
+    stage('build pdf') {
+        sh '''
+        . /home/jenkins/secopvenv/bin/activate
+        make -C doc pdf
+        '''
+    }
 
     stage('build man') {
         sh '''
diff --git a/doc/source/conf.py b/doc/source/conf.py
index b9006c3..f76e1d7 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -43,7 +43,9 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.intersphinx',
               'sphinx.ext.todo',
               'sphinx.ext.mathjax',
-              'sphinx.ext.viewcode']
+              'sphinx.ext.viewcode',
+              'rst2pdf.pdfbuilder',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -220,3 +222,80 @@ from frappy.lib.classdoc import class_doc_handler
 
 def setup(app):
     app.connect('autodoc-process-docstring', class_doc_handler)
+
+
+# -- Options for PDF output --------------------------------------------------
+# Grouping the document tree into PDF files. List of tuples
+# (source start file, target name, title, author, options).
+#
+# If there is more than one author, separate them with \\.
+# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
+#
+# The options element is a dictionary that lets you override
+# this config per-document. For example:
+#
+# ('index', 'MyProject', 'My Project', 'Author Name', {'pdf_compressed': True})
+#
+# would mean that specific document would be compressed
+# regardless of the global 'pdf_compressed' setting.
+pdf_documents = [
+    ('index', project, project, author),
+]
+# A comma-separated list of custom stylesheets. Example:
+pdf_stylesheets = ['sphinx', 'a4']
+# A list of folders to search for stylesheets. Example:
+pdf_style_path = ['.', '_styles']
+# Create a compressed PDF
+# Use True/False or 1/0
+# Example: compressed=True
+# pdf_compressed = False
+# A colon-separated list of folders to search for fonts. Example:
+# pdf_font_path = ['/usr/share/fonts', '/usr/share/texmf-dist/fonts/']
+# Language to be used for hyphenation support
+# pdf_language = "en_US"
+# Mode for literal blocks wider than the frame. Can be
+# overflow, shrink or truncate
+# pdf_fit_mode = "shrink"
+# Section level that forces a break page.
+# For example: 1 means top-level sections start in a new page
+# 0 means disabled
+# pdf_break_level = 0
+# When a section starts in a new page, force it to be 'even', 'odd',
+# or just use 'any'
+# pdf_breakside = 'any'
+# Insert footnotes where they are defined instead of
+# at the end.
+# pdf_inline_footnotes = True
+# verbosity level. 0 1 or 2
+# pdf_verbosity = 0
+# If false, no index is generated.
+# pdf_use_index = True
+# If false, no modindex is generated.
+# pdf_use_modindex = True
+# If false, no coverpage is generated.
+# pdf_use_coverpage = True
+# Name of the cover page template to use
+# pdf_cover_template = 'sphinxcover.tmpl'
+# Documents to append as an appendix to all manuals.
+# pdf_appendices = []
+# Enable experimental feature to split table cells. Use it
+# if you get "DelayedTable too big" errors
+# pdf_splittables = False
+# Set the default DPI for images
+# pdf_default_dpi = 72
+# Enable rst2pdf extension modules
+# pdf_extensions = []
+# Page template name for "regular" pages
+# pdf_page_template = 'cutePage'
+# Show Table Of Contents at the beginning?
+# pdf_use_toc = True
+# How many levels deep should the table of contents be?
+pdf_toc_depth = 9999
+# Add section number to section references
+pdf_use_numbered_links = False
+# Background images fitting mode
+pdf_fit_background_mode = 'scale'
+# Repeat table header on tables that cross a page boundary?
+pdf_repeat_table_rows = True
+# Enable smart quotes (1, 2 or 3) or disable by setting to 0
+pdf_smartquotes = 0
diff --git a/requirements-dev.txt b/requirements-dev.txt
index 2c97239..3098842 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -3,6 +3,7 @@ sphinx_rtd_theme
 Sphinx>=1.2.1
 # for generating docu
 markdown>=2.6
+rst2pdf
 # test suite
 pytest
 pytest-randomly>=1.1