Feat/latex customization (#45)

* add required logos for the coverpage * add style file and modify it in conf file * add sphinx extension for image conversion. * modify badge name for latex read * add only directive for badges in rst file * update workflow for pdf build * update readme for badges not applicable for latex * customize makefile for pdf to avoid badge issue * update make.bat file for pdf build * update workflow for html and pdf * modify makefile for pdf build * add required logos for the coverpage * add style file and modify it in conf file * add sphinx extension for image conversion. * modify badge name for latex read * add only directive for badges in rst file * update workflow for pdf build * update readme for badges not applicable for latex * customize makefile for pdf to avoid badge issue * update make.bat file for pdf build * update workflow for html and pdf * modify makefile for pdf build * Generate PDF docs in CI * update workflow for docs * Apply suggestions from code review Co-authored-by: Jorge Martínez <[email protected]> * update readme and remove unwanted file * add latex elements to init file of theme * add preject name as title for doc * add project name as title for doc * add logo for pdf doc * add date of pdf as build date and year * Add latex folder to import preamble * Add requirements to toml file * Update src/pyansys_sphinx_theme/latex/__init__.py Co-authored-by: Kathy Pippert <[email protected]> * Update year to the preamble * Apply suggestions from code review Co-authored-by: Jorge Martínez <[email protected]> * Apply suggested changes * Add variables to latex using jinja Co-authored-by: Jorge Martínez Garrido <[email protected]> Co-authored-by: Jorge Martínez <[email protected]> Co-authored-by: Kathy Pippert <[email protected]>
ansys · May 24, 2022 · a11d663 · a11d663
1 parent 914601c
commit a11d663
Show file tree

Hide file tree

Showing 13 changed files with 218 additions and 13 deletions.
diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml
@@ -38,17 +38,31 @@ jobs:
 
       - name: Install dependencies
         run: |
+          sudo apt update
+          sudo apt-get install -y build-essential zip pandoc texlive-latex-extra latexmk texlive-pstricks
           python -m pip install --upgrade pip tox
-      - name: Build documentation
+          python -m pip install -r requirements/requirements_doc.txt
+          python -m pip install --editable .
+      - name: Build HTML documentation
         run: tox -e doc
 
-      - name: Upload Documentation
+      - name: Upload HTML Documentation
         uses: actions/[email protected]
         with:
-          name: Documentation
+          name: HTML-Documentation
           path: .tox/doc_out/
           retention-days: 7
 
+      - name: Build PDF Documentation
+        run: |
+          make -C doc pdf
+      - name: Upload PDF Documentation
+        uses: actions/upload-artifact@v2
+        with:
+          name: PDF-Documentation
+          path: doc/build/latex/pyansys*.pdf
+          retention-days: 7
+
       - name: Deploy to gh-pages
         if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
         uses: JamesIves/[email protected]
@@ -89,7 +103,7 @@ jobs:
       - name: Upload wheel and sdist to artifacts
         uses: actions/upload-artifact@v2
         with:
-          name: pyasys-templates-packages
+          name: pyasys-sphinx-theme
           path: dist/
           retention-days: 7
 
@@ -126,4 +140,4 @@ jobs:
       - name: Release
         uses: softprops/action-gh-release@v1
         with:
-          generate_release_notes: true
+          generate_release_notes: true
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -26,13 +26,13 @@ repos:
     additional_dependencies: [toml]
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.1.0
+  rev: v4.2.0
   hooks:
   - id: check-merge-conflict
   - id: debug-statements
 
 # this validates our github workflow files
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.14.0
+  rev: 0.15.0
   hooks:
     - id: check-github-workflows
diff --git a/README.rst b/README.rst
@@ -26,7 +26,7 @@ PyAnsys Sphinx Theme
    :target: https://opensource.org/licenses/MIT
    :alt: MIT
 
-.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat
+.. |black| image:: https://img.shields.io/badge/code_style-black-000000.svg?style=flat
    :target: https://github.com/psf/black
    :alt: Black
 

diff --git a/doc/Makefile b/doc/Makefile
@@ -17,9 +17,14 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-
+
 # customized clean due to api examples
 clean:
 	rm -rf build
 	find . -type d -name "_autosummary" -exec rm -rf {} +
+
+# customized pdf due to svg issue
+pdf:
+	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	cd build/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
+	(test -f build/latex/pyansys*.pdf && echo pdf exists) || exit 1
diff --git a/doc/make.bat b/doc/make.bat
@@ -11,6 +11,7 @@ set SOURCEDIR=source
 set BUILDDIR=build
 
 if "%1" == "" goto help
+if "%1" == "pdf" goto pdf
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -31,5 +32,10 @@ goto end
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
+:pdf
+	%SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+	cd "%BUILDDIR%\latex"
+	pdflatex pyansys_sphinx_theme.tex --interaction=nonstopmode
+
 :end
 popd
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -1,7 +1,19 @@
 """Sphinx documentation configuration file."""
 from datetime import datetime
 
-from pyansys_sphinx_theme import __version__, ansys_favicon, pyansys_logo_black
+from sphinx.builders.latex import LaTeXBuilder
+
+LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
+
+from pyansys_sphinx_theme import (
+    __version__,
+    ansys_favicon,
+    ansys_logo_white,
+    ansys_logo_white_cropped,
+    latex,
+    pyansys_logo_black,
+    watermark,
+)
 
 # Project information
 project = "pyansys_sphinx_theme"
@@ -23,7 +35,6 @@
 
 html_short_title = html_title = "PyAnsys Sphinx Theme"
 
-
 # Sphinx extensions
 extensions = [
     "sphinx.ext.autodoc",
@@ -80,3 +91,10 @@
 
 # The master toctree document.
 master_doc = "index"
+
+# additional logos for the latex coverpage
+latex_additional_files = [watermark, ansys_logo_white, ansys_logo_white_cropped]
+
+# change the preamble of latex with customized title page
+# variables are the title of pdf, watermark
+latex_elements = {"preamble": latex.generate_preamble(html_title)}
diff --git a/pyproject.toml b/pyproject.toml
@@ -26,6 +26,7 @@ classifiers = [
 dependencies = [
     "Sphinx>=4.0.0",
     "pydata-sphinx-theme==0.8.1",
+    "Jinja2>=3.1.2",
 ]
 
 [project.entry-points."sphinx.html_themes"]

diff --git a/src/pyansys_sphinx_theme/__init__.py b/src/pyansys_sphinx_theme/__init__.py
@@ -10,7 +10,9 @@
 pyansys_logo_black = os.path.join(_this_path, "static", "pyansys-logo-black-cropped.png")
 pyansys_logo_white = os.path.join(_this_path, "static", "pyansys-logo-white-cropped.png")
 ansys_favicon = os.path.join(_this_path, "static", "ansys-favicon.png")
-
+ansys_logo_white = os.path.join(_this_path, "static", "ansys_logo_white.pdf")
+ansys_logo_white_cropped = os.path.join(_this_path, "static", "ansys_logo_white_cropped.pdf")
+watermark = os.path.join(_this_path, "static", "watermark.pdf")
 
 html_logo = pyansys_logo_black
 

diff --git a/src/pyansys_sphinx_theme/latex/__init__.py b/src/pyansys_sphinx_theme/latex/__init__.py
@@ -0,0 +1,48 @@
+"""This module creates the title page for a LaTeX pdf."""
+from datetime import datetime
+import os
+from pathlib import Path
+
+import jinja2
+
+LATEX_SUBPKG = Path(os.path.dirname(os.path.realpath(__file__)))
+COVER_TEX = LATEX_SUBPKG / "cover.tex"
+
+
+def generate_preamble(title, watermark="watermark", date=None):
+    """Generate the preamble for the PDF documentation.
+
+    Parameters
+    ----------
+    title : str
+        Title of the document.
+    watermark : str, optional
+        Name of the watermark image.
+    date : ~datetime.datetime, optional
+        Date of document generation. If not provided, today's date is used.
+
+    Returns
+    -------
+    str
+        A string representing the LaTeX source code for the preamble.
+
+    """
+    if date is None:
+        date = datetime.today()
+    variables = dict(_title=title, _watermark=watermark, _date=date)
+
+    latex_jinja_env = jinja2.Environment(
+        block_start_string="\BLOCK{",
+        block_end_string="}",
+        variable_start_string="\pyvar{",
+        variable_end_string="}",
+        comment_start_string="\#{",
+        comment_end_string="}",
+        line_statement_prefix="%%",
+        line_comment_prefix="%#",
+        trim_blocks=True,
+        autoescape=False,
+        loader=jinja2.FileSystemLoader(COVER_TEX),
+    )
+    template = latex_jinja_env.get_template(".")
+    return template.render(variables)
diff --git a/src/pyansys_sphinx_theme/latex/cover.tex b/src/pyansys_sphinx_theme/latex/cover.tex
@@ -0,0 +1,111 @@
+\renewcommand{\sphinxmaketitle}{%
+    \newsavebox\imagebox
+    \newsavebox\myTitle
+    % native LaTeX command. Specifies a page with no formatting.
+    % Page number restarts after this page
+    \begin{titlepage}
+    % san serif
+    \sffamily
+    %
+    % set to 0 so that we don't have any blank space at the top of the page
+    \topskip0pt
+    %
+    % removes all margins
+    \advance\voffset -1in %
+    \advance\hoffset -1in %
+    \advance\vsize 2in %
+    \advance\hsize 2in %
+    %
+    % load the graphics into a LaTeX (not TeX) "savebox". We use this load
+    % to obtain the height later, and to insert it into the doc later
+    \sbox{\imagebox}{\includegraphics{\pyvar{_watermark}}}%
+    %
+    % put the picture in a zero sized box to get a "background effect"
+    % everything else will draw over it
+    \hbox to 0in {\vbox to 0in {\usebox{\imagebox}}}
+    %
+    % how it worked before savebox method
+    %\hbox to 0in {\vbox to 0in {\includegraphics{\pyvar{_watermark}}}} %
+    % Where the right boundary of the title block goes
+    %
+    % Define "ansysBlockWidth" <-- exactly what its name implies
+    \newdimen\ansysBlockWidth\ansysBlockWidth = 3in %
+    % Define "ansysBlockDistanceFromRightEdge" <-- exactly what its name implies
+    \newdimen\ansysBlockDistanceFromRightEdge \ansysBlockDistanceFromRightEdge = 0.5in %
+    % Define "distanceToBottomOfAnsysBox" <-- length from top of page to bottom of title box
+    \newdimen\distanceToBottomOfAnsysBox %
+    \distanceToBottomOfAnsysBox=\ht\imagebox %
+    \advance\distanceToBottomOfAnsysBox -\lineskip %
+    \advance\distanceToBottomOfAnsysBox -0.125in %
+    % Define "myHBoxWidth" <-- distance from left edge of page to right edge Ansys box
+    \newdimen\myHBoxWidth
+    \myHBoxWidth=\hsize \advance\myHBoxWidth-\ansysBlockDistanceFromRightEdge
+    % implement the Ansys block
+    \hbox to \myHBoxWidth {\vbox to \distanceToBottomOfAnsysBox {}  %
+        \hfil
+        %
+        % draw the box
+        \parbox[b]{\ansysBlockWidth}{\raggedleft {
+            \includegraphics{ansys_logo_white}} \\
+            \footnotesize
+            \textcolor{lightgray}
+            \hrule
+            \vskip 6pt
+            \textcopyright{} {\pyvar{_date.year}} ANSYS, Inc. or affiliated companies\\
+            Unauthorized use, distribution, or duplication prohibited.}
+    } %
+    %we use a save box method so that we can get draw the bottom material with respect
+    %to the bottom of the page
+    \sbox{\myTitle}{\vbox{
+    %vskip skips down a specified distance from the previous Ansys block and picture
+    \vskip 1in
+    %title
+    \centerline{\huge \bfseries {\pyvar{_title}}}
+    \vskip 6pt
+    %line under title
+    \centerline{\vrule height 0.0625in  width 6.5in}
+    }
+    }
+    \usebox{\myTitle} \\%
+    \newdimen\toBottom%
+    %trying to calculate distance from the bottom of the line under the title
+    %to the bottom of the page, used to construct a strut (0 width vbox)
+    \toBottom=\vsize%
+    \advance\toBottom -\ht\myTitle %
+    \advance\toBottom -\distanceToBottomOfAnsysBox%
+    \advance\toBottom -\baselineskip%
+    \advance\toBottom -\lineskip%
+    \advance\toBottom -0.5in
+    \hbox to \hsize{%
+        %0 width vbox (empty vbox)
+        \vbox to \toBottom {}%
+        %distance from the left side
+        \hskip 1in%
+        %left block
+        \parbox[b]{2in}{
+            {\includegraphics{ansys_logo_white_cropped}} \\
+            ANSYS, Inc.\\
+            Southpointe\\
+            2600 Ansys Drive\\
+            Canonsburg, PA 15317\\
+            \href{mailto:[email protected]}{[email protected]}\\
+            \url{http://www.ansys.com}\\
+            (T) 724-746-3304\\
+            (F) 724-514-9494
+        }%
+        \hfil%
+        %hfil pushes the right box to the right
+        %we needed the vbox since we are stacking two objects on the right side
+        \vbox{\hbox {\pyvar{_date.strftime('%b %d, %Y').capitalize()}} \vskip 0.5\baselineskip%\footnotesize
+        %fbox is a horizontal box, so we need to put a vbox in it to get multiple lines.
+        %the fbox is wrapped in an hbox so we can control where it goes.
+        %we stack the hboxes in the vbox. We need the hboxes because otherwise the fbox had
+        %a huge width
+            \hbox{\fbox{\vbox{\hbox{ANSYS, Inc. and}\hbox{ANSYS Europe,}
+            \hbox{Ltd. are UL}\hbox{registered ISO}\hbox{9001:2015}\hbox{companies.}}}}%
+        }
+        %1in of space between the right box and the right edge of the page
+        \hskip 1in%
+    }
+    \end{titlepage}
+}
diff --git a/src/pyansys_sphinx_theme/static/ansys_logo_white.pdf b/src/pyansys_sphinx_theme/static/ansys_logo_white.pdf
diff --git a/src/pyansys_sphinx_theme/static/ansys_logo_white_cropped.pdf b/src/pyansys_sphinx_theme/static/ansys_logo_white_cropped.pdf
diff --git a/src/pyansys_sphinx_theme/static/watermark.pdf b/src/pyansys_sphinx_theme/static/watermark.pdf