From c8be6ff19d056f79bc8fd17d57b236bbaaa0aa87 Mon Sep 17 00:00:00 2001 From: Sebastian Gode Date: Tue, 6 Aug 2024 09:08:14 +0000 Subject: [PATCH] Added sphinx latex templates for customizing PDF output --- otc_metadata/templates/conf.py.j2 | 2 + .../templates/latex_templates/latex.tex.jinja | 108 ++++++++++++++++++ .../latex_templates/longtable.tex.jinja | 74 ++++++++++++ .../latex_templates/sphinxmessages.sty.jinja | 21 ++++ .../latex_templates/tabular.tex.jinja | 54 +++++++++ .../latex_templates/tabulary.tex.jinja | 54 +++++++++ tools/generate_doc_confpy.py | 20 ++++ 7 files changed, 333 insertions(+) create mode 100644 otc_metadata/templates/latex_templates/latex.tex.jinja create mode 100644 otc_metadata/templates/latex_templates/longtable.tex.jinja create mode 100644 otc_metadata/templates/latex_templates/sphinxmessages.sty.jinja create mode 100644 otc_metadata/templates/latex_templates/tabular.tex.jinja create mode 100644 otc_metadata/templates/latex_templates/tabulary.tex.jinja diff --git a/otc_metadata/templates/conf.py.j2 b/otc_metadata/templates/conf.py.j2 index 7db2f711..589a0f96 100644 --- a/otc_metadata/templates/conf.py.j2 +++ b/otc_metadata/templates/conf.py.j2 @@ -131,3 +131,5 @@ latex_documents = [ {% endif -%} ] +# Path for the latex templates +templates_path = ['_templates'] diff --git a/otc_metadata/templates/latex_templates/latex.tex.jinja b/otc_metadata/templates/latex_templates/latex.tex.jinja new file mode 100644 index 00000000..deb03050 --- /dev/null +++ b/otc_metadata/templates/latex_templates/latex.tex.jinja @@ -0,0 +1,108 @@ +%% Generated by Sphinx. +\def\sphinxdocclass{<%= docclass %>} +<% if latex_engine == 'lualatex' -%> +\IfFileExists{luatex85.sty} + {\RequirePackage{luatex85}} + {\ifdefined\luatexversion\ifnum\luatexversion>84\relax + \PackageError{sphinx} + {** With this LuaTeX (\the\luatexversion),Sphinx requires luatex85.sty **} + {** Add the LaTeX package luatex85 to your TeX installation, and try again **} + \endinput\fi\fi} +<% endif -%> +\documentclass[<%= papersize %>,<%= pointsize %><%= classoptions %>]{<%= wrapperclass %>} +\ifdefined\pdfpxdimen + \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen +\fi \sphinxpxdimen=<%= pxunit %>\relax +\ifdefined\pdfimageresolution + \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax +\fi +%% let collapsible pdf bookmarks panel have high depth per default +\PassOptionsToPackage{bookmarksdepth=5}{hyperref} +<% if use_xindy -%> +%% turn off hyperref patch of \index as sphinx.xdy xindy module takes care of +%% suitable \hyperpage mark-up, working around hyperref-xindy incompatibility +\PassOptionsToPackage{hyperindex=false}{hyperref} +%% memoir class requires extra handling +\makeatletter\@ifclassloaded{memoir} +{\ifdefined\memhyperindexfalse\memhyperindexfalse\fi}{}\makeatother +<% endif %> +<% if booktabs -%> +\PassOptionsToPackage{booktabs}{sphinx} +<% endif -%> +<% if borderless -%> +\PassOptionsToPackage{borderless}{sphinx} +<% endif -%> +<% if colorrows -%> +\PassOptionsToPackage{colorrows}{sphinx} +<% endif -%> +<%= passoptionstopackages %> +\PassOptionsToPackage{warn}{textcomp} +<%= inputenc %> +<%= utf8extra %> +<%= cmappkg %> +<%= fontenc %> +<%= amsmath %> +<%= multilingual %> +<%= substitutefont %> +<%= textcyrillic %> +<%= fontpkg %> +<%= fontsubstitution %> +<%= textgreek %> +<%= fncychap %> +\usepackage<%= sphinxpkgoptions %>{sphinx} +<%= sphinxsetup %> +<%= fvset %> +<%= geometry %> +<%= extrapackages %> + +<%- for name, option in packages %> +<%- if option %> +\usepackage[<%= option %>]{<%= name %>} +<%- else %> +\usepackage{<%= name %>} +<%- endif %> +<%- endfor %> + +<%= hyperref %> +<%- for name, option in packages_after_hyperref %> +<%- if option %> +\usepackage[<%= option %>]{<%= name %>} +<%- else %> +\usepackage{<%= name %>} +<%- endif %> +<%- endfor %> + +<%= contentsname %> +\usepackage{sphinxmessages} +<%= tocdepth %> +<%= secnumdepth %> +<%= preamble %> + +\title{<%= title %>} +\date{<%= date %>} +\release{<%= release | e %>} +\author{<%= author %>} +<%- if logofilename %> +\newcommand{\sphinxlogo}{\sphinxincludegraphics{<%= logofilename %>}\par} +<%- else %> +\newcommand{\sphinxlogo}{\vbox{}} +<%- endif %> +<%- if releasename or release %> +\renewcommand{\releasename}{<%= releasename or _('Release') | e %>} +<%- else %> +\renewcommand{\releasename}{} +<%- endif %> +<%= makeindex %> +\begin{document} +<%= shorthandoff %> +\pagestyle{empty} +<%= maketitle %> +\pagestyle{plain} +<%= tableofcontents %> +\pagestyle{normal} +<%= body %> +<%= atendofbody %> +<%= indices %> +\renewcommand{\indexname}{<%= _('Index') | e %>} +<%= printindex %> +\end{document} diff --git a/otc_metadata/templates/latex_templates/longtable.tex.jinja b/otc_metadata/templates/latex_templates/longtable.tex.jinja new file mode 100644 index 00000000..83790f4b --- /dev/null +++ b/otc_metadata/templates/latex_templates/longtable.tex.jinja @@ -0,0 +1,74 @@ +\begin{savenotes} +\sphinxatlongtablestart +\sphinxthistablewithglobalstyle +<% if 'booktabs' in table.styles -%> +\sphinxthistablewithbooktabsstyle +<% endif -%> +<% if 'borderless' in table.styles -%> +\sphinxthistablewithborderlessstyle +<% endif -%> +<% if 'standard' in table.styles -%> +\sphinxthistablewithstandardstyle +<% endif -%> +<% if 'vlines' in table.styles -%> +\sphinxthistablewithvlinesstyle +<% endif -%> +<% if 'novlines' in table.styles -%> +\sphinxthistablewithnovlinesstyle +<% endif -%> +<% if 'colorrows' in table.styles -%> +\sphinxthistablewithcolorrowsstyle +<% endif -%> +<% if 'nocolorrows' in table.styles -%> +\sphinxthistablewithnocolorrowsstyle +<% endif -%> +\makeatletter +<%- if table.align in ('center', 'default') %> + \LTleft \@totalleftmargin plus1fill + \LTright\dimexpr\columnwidth-\@totalleftmargin-\linewidth\relax plus1fill +<%- elif table.align == 'left' %> + \LTleft \@totalleftmargin + \LTright\dimexpr\columnwidth-\@totalleftmargin-\linewidth\relax plus1fill +<%- elif table.align == 'right' %> + \LTleft \@totalleftmargin plus1fill + \LTright\dimexpr\columnwidth-\@totalleftmargin-\linewidth\relax +<%- endif %> +\makeatother +\begin{longtable}<%= table.get_colspec() %> +<%- if table.caption -%> +\sphinxthelongtablecaptionisattop +\caption{<%= ''.join(table.caption) %>\strut}<%= labels %>\\*[\sphinxlongtablecapskipadjust] +<% elif labels -%> +\noalign{\phantomsection<%= labels %>}% +<% endif -%> +\sphinxtoprule +<%= ''.join(table.header) -%> +<%- if table.header -%> +\sphinxmidrule +<% endif -%> +\endfirsthead + +\multicolumn{<%= table.colcount %>}{c}{\sphinxnorowcolor + \makebox[0pt]{\sphinxtablecontinued{\tablename\ \thetable{} \textendash{} <%= _('continued from previous page') %>}}% +}\\ +\sphinxtoprule +<%= ''.join(table.header) -%> +<%- if table.header -%> +\sphinxmidrule +<% endif -%> +\endhead + +\sphinxbottomrule +\multicolumn{<%= table.colcount %>}{r}{\sphinxnorowcolor + \makebox[0pt][r]{\sphinxtablecontinued{<%= _('continues on next page') %>}}% +}\\ +\endfoot + +\endlastfoot +\sphinxtableatstartofbodyhook +<%= ''.join(table.body) -%> +\sphinxbottomrule +\end{longtable} +\sphinxtableafterendhook +\sphinxatlongtableend +\end{savenotes} diff --git a/otc_metadata/templates/latex_templates/sphinxmessages.sty.jinja b/otc_metadata/templates/latex_templates/sphinxmessages.sty.jinja new file mode 100644 index 00000000..ef2750f6 --- /dev/null +++ b/otc_metadata/templates/latex_templates/sphinxmessages.sty.jinja @@ -0,0 +1,21 @@ +% +% sphinxmessages.sty +% +% message resources for Sphinx +% +\ProvidesPackage{sphinxmessages}[2019/01/04 v2.0 Localized LaTeX macros (Sphinx team)] + +\renewcommand{\literalblockcontinuedname}{<%= _('continued from previous page') | e %>} +\renewcommand{\literalblockcontinuesname}{<%= _('continues on next page') | e %>} +\renewcommand{\sphinxnonalphabeticalgroupname}{<%= _('Non-alphabetical') | e %>} +\renewcommand{\sphinxsymbolsname}{<%= _('Symbols') | e %>} +\renewcommand{\sphinxnumbersname}{<%= _('Numbers') | e %>} +\def\pageautorefname{<%= _('page') | e %>} + +<%= addtocaptions %>{\renewcommand{\figurename}{<%= figurename[0] | e | eabbr %>}} +\def\fnum@figure{\figurename\thefigure{}<%= figurename[1] | e %>} + +<%= addtocaptions %>{\renewcommand{\tablename}{<%= tablename[0] | e | eabbr %>}} +\def\fnum@table{\tablename\thetable{}<%= tablename[1] | e %>} + +<%= addtocaptions %>{\renewcommand{\literalblockname}{<%= literalblockname[0].strip() %>}} diff --git a/otc_metadata/templates/latex_templates/tabular.tex.jinja b/otc_metadata/templates/latex_templates/tabular.tex.jinja new file mode 100644 index 00000000..0a9310a5 --- /dev/null +++ b/otc_metadata/templates/latex_templates/tabular.tex.jinja @@ -0,0 +1,54 @@ +\begin{savenotes}\sphinxattablestart +\sphinxthistablewithglobalstyle +<% if 'booktabs' in table.styles -%> +\sphinxthistablewithbooktabsstyle +<% endif -%> +<% if 'borderless' in table.styles -%> +\sphinxthistablewithborderlessstyle +<% endif -%> +<% if 'standard' in table.styles -%> +\sphinxthistablewithstandardstyle +<% endif -%> +<% if 'vlines' in table.styles -%> +\sphinxthistablewithvlinesstyle +<% endif -%> +<% if 'novlines' in table.styles -%> +\sphinxthistablewithnovlinesstyle +<% endif -%> +<% if 'colorrows' in table.styles -%> +\sphinxthistablewithcolorrowsstyle +<% endif -%> +<% if 'nocolorrows' in table.styles -%> +\sphinxthistablewithnocolorrowsstyle +<% endif -%> +<% if table.align -%> + <%- if table.align in ('center', 'default') -%> + \centering + <%- elif table.align == 'left' -%> + \raggedright + <%- else -%> + \raggedleft + <%- endif %> +<%- else -%> + \centering +<%- endif %> +<% if table.caption -%> +\sphinxcapstartof{table} +\sphinxthecaptionisattop +\sphinxcaption{<%= ''.join(table.caption) %>}<%= labels %> +\sphinxaftertopcaption +<% elif labels -%> +\phantomsection<%= labels %>\nobreak +<% endif -%> +\begin{tabular}[t]<%= table.get_colspec() -%> +\sphinxtoprule +<%= ''.join(table.header) -%> +<%- if table.header -%> +\sphinxmidrule +<% endif -%> +\sphinxtableatstartofbodyhook +<%=- ''.join(table.body) -%> +\sphinxbottomrule +\end{tabular} +\sphinxtableafterendhook\par +\sphinxattableend\end{savenotes} diff --git a/otc_metadata/templates/latex_templates/tabulary.tex.jinja b/otc_metadata/templates/latex_templates/tabulary.tex.jinja new file mode 100644 index 00000000..6ebcec6d --- /dev/null +++ b/otc_metadata/templates/latex_templates/tabulary.tex.jinja @@ -0,0 +1,54 @@ +\begin{savenotes}\sphinxattablestart +\sphinxthistablewithglobalstyle +<% if 'booktabs' in table.styles -%> +\sphinxthistablewithbooktabsstyle +<% endif -%> +<% if 'borderless' in table.styles -%> +\sphinxthistablewithborderlessstyle +<% endif -%> +<% if 'standard' in table.styles -%> +\sphinxthistablewithstandardstyle +<% endif -%> +<% if 'vlines' in table.styles -%> +\sphinxthistablewithvlinesstyle +<% endif -%> +<% if 'novlines' in table.styles -%> +\sphinxthistablewithnovlinesstyle +<% endif -%> +<% if 'colorrows' in table.styles -%> +\sphinxthistablewithcolorrowsstyle +<% endif -%> +<% if 'nocolorrows' in table.styles -%> +\sphinxthistablewithnocolorrowsstyle +<% endif -%> +<% if table.align -%> + <%- if table.align in ('center', 'default') -%> + \centering + <%- elif table.align == 'left' -%> + \raggedright + <%- else -%> + \raggedleft + <%- endif %> +<%- else -%> + \centering +<%- endif %> +<% if table.caption -%> +\sphinxcapstartof{table} +\sphinxthecaptionisattop +\sphinxcaption{<%= ''.join(table.caption) %>}<%= labels %> +\sphinxaftertopcaption +<% elif labels -%> +\phantomsection<%= labels %>\nobreak +<% endif -%> +\begin{tabulary}{\linewidth}[t]<%= table.get_colspec() -%> +\sphinxtoprule +<%= ''.join(table.header) -%> +<%- if table.header -%> +\sphinxmidrule +<% endif -%> +\sphinxtableatstartofbodyhook +<%=- ''.join(table.body) -%> +\sphinxbottomrule +\end{tabulary} +\sphinxtableafterendhook\par +\sphinxattableend\end{savenotes} diff --git a/tools/generate_doc_confpy.py b/tools/generate_doc_confpy.py index ea4562e6..3071871a 100644 --- a/tools/generate_doc_confpy.py +++ b/tools/generate_doc_confpy.py @@ -15,8 +15,10 @@ import argparse import logging +import os.path import pathlib import requests +import shutil import subprocess from git import exc @@ -48,6 +50,7 @@ def process_repositories(args, service): env = Environment( loader=PackageLoader("otc_metadata"), autoescape=select_autoescape() ) + metadata_path = os.path.dirname(os.path.abspath(os.path.dirname(__file__))) conf_py_template = env.get_template("conf.py.j2") tox_ini_template = env.get_template("tox.ini.j2") zuul_yaml_template = env.get_template("zuul.yaml.j2") @@ -130,6 +133,23 @@ def process_repositories(args, service): logging.debug(f"Analyzing document {doc}") conf_py_path = pathlib.Path(copy_to, doc["rst_location"], "conf.py") + latex_templates_src_path = pathlib.Path(metadata_path, "otc_metadata", "templates", "latex_templates") + latex_templates_dest_path = pathlib.Path(copy_to, doc["rst_location"], "_templates") + + # Check if the latex destination path exists and is a directory + if not latex_templates_dest_path.exists(): + logging.info(f"Path for latex templates in {doc['title']} does not exist") + latex_templates_dest_path.mkdir(parents=True, exist_ok=True) + + # Delete all files in the latex destination directory + for file in latex_templates_dest_path.iterdir(): + if file.is_file(): + file.unlink() + + # Add the new templates + for file in latex_templates_src_path.iterdir(): + shutil.copy2(file, latex_templates_dest_path) + if not conf_py_path.exists(): logging.info(f"Path for document {doc['title']} does not exist") conf_py_path.parent.mkdir(parents=True, exist_ok=True)