DOC: Generate pdf documentation in CI (#354)

.github/workflows/ci_cd.yml

@@ -63,31 +63,18 @@ jobs:
         # Only the tox environment specified in the tox.ini gh-actions is run
         run: tox -e test -- --ignore=tests/e2e
 
-  # TODO: convert to ansys/actions/doc-build
   doc-build:
-    name: Build documentation
+    name: "Doc build"
     runs-on: ubuntu-latest
-    needs: [doc-style]
+    needs: doc-style
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: "Build documentation"
+        uses: ansys/actions/doc-build@main
         with:
+          skip-install: true
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade .[doc] tox
-
-      - name: Generate the documentation with tox
-        run: tox -e doc
-
-      - name: Upload HTML Documentation
-        uses: actions/upload-artifact@v4
-        with:
-          name: documentation-html
-          path: .tox/doc_out
-          retention-days: 7
+          use-python-cache: false
+          sphinxopts: '-j auto -w build_errors.txt -N -q'
 
   package:
     name: Package library

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -j auto
+SPHINXOPTS    = -j auto -w build_errors.txt -N -q
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build
@@ -24,3 +24,8 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf $(SOURCEDIR)/examples
 	find . -type d -name "_autosummary" -exec rm -rf {} +
+
+pdf:
+	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
+	(test -f $(BUILDDIR)/latex/ansys-edb-core.pdf && echo pdf exists) || exit 1

doc/make.bat

@@ -7,11 +7,15 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
+if "%SPHINXOPTS%" == "" (
+	set SPHINXOPTS = -j auto -w build_errors.txt -N -q
+)
 set SOURCEDIR=source
 set BUILDDIR=_build
 
 if "%1" == "" goto help
 if "%1" == "clean" goto clean
+if "%1" == "pdf" goto pdf
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -34,6 +38,17 @@ rmdir /s /q %BUILDDIR% > /NUL 2>&1
 for /d /r %SOURCEDIR% %%d in (_autosummary) do @if exist "%%d" rmdir /s /q "%%d"
 goto end
 
+:pdf
+%SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+cd "%BUILDDIR%\latex"
+for %%f in (*.tex) do (
+pdflatex "%%f" --interaction=nonstopmode)
+if NOT EXIST ansys-edb-core.pdf (
+	Echo "no pdf generated!"
+	exit /b 1)
+Echo "pdf generated!"
+goto end
+
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 

doc/source/conf.py

@@ -3,10 +3,21 @@
 import os
 import sys
 
-from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
+from ansys_sphinx_theme import (
+    ansys_favicon,
+    ansys_logo_white,
+    ansys_logo_white_cropped,
+    get_version_match,
+    latex,
+    pyansys_logo_black,
+    watermark,
+)
+from sphinx.builders.latex import LaTeXBuilder
 
 from ansys.edb.core import __version__
 
+LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
+
 # Project information
 project = "ansys-edb-core"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
@@ -46,6 +57,13 @@
 
 html_static_path = ["_static"]
 
+# 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)}
+
 # Sphinx extensions
 extensions = [
     "sphinx.ext.autodoc",

pyproject.toml

@@ -51,7 +51,7 @@ tests = [
 ]
 # FIXME: update to newer versions
 doc = [
-    "sphinx==7.1.2",
+    "sphinx==7.2.6",
     "numpydoc==1.6.0",
     "ansys_sphinx_theme>=0.12.2",
     "sphinx-copybutton==0.5.2",

src/ansys/edb/core/database.py

@@ -34,14 +34,7 @@
 
 
 class ProductIdType(Enum):
-    """Provides an enum representing IDs of Ansys products that support EDB usage.
-
-    - HFSS_3D_LAYOUT
-    - DESIGNER (Deprecated. Use ``HFSS_3D_LAYOUT`` instead.)
-    - SIWAVE
-    - GENERIC_TRANSLATOR
-    - USER_DEFINED
-    """
+    """Provides an enum representing IDs of Ansys products that support EDB usage."""
 
     HFSS_3D_LAYOUT = DESIGNER = edb_defs_pb2.DESIGNER
     SIWAVE = edb_defs_pb2.SI_WAVE

src/ansys/edb/core/definition/bondwire_def.py

@@ -45,15 +45,7 @@ def bondwire_def_str_message(obj, string):
 
 
 class BondwireDefType(Enum):
-    """Provides an enum representing bondwire types.
-
-    - APD_BONDWIRE_DEF
-       APD bondwire.
-    - JEDEC4_BONDWIRE_DEF
-       JEDEC4 bondwire.
-    - JEDEC5_BONDWIRE_DEF
-       JEDEC5 bondwire.
-    """
+    """Enum representing different types of bondwires."""
 
     APD_BONDWIRE_DEF = pb.APD_BONDWIRE_DEF
     JEDEC4_BONDWIRE_DEF = pb.JEDEC4_BONDWIRE_DEF

src/ansys/edb/core/definition/die_property.py

@@ -12,23 +12,14 @@
 
 
 class DieOrientation(Enum):
-    """Provides an enum representing die orientations.
-
-    - CHIP_UP
-    - CHIP_DOWN
-    """
+    """Provides an enum representing die orientations."""
 
     CHIP_UP = die_property_pb2.DIE_ORIENTATION_CHIP_UP
     CHIP_DOWN = die_property_pb2.DIE_ORIENTATION_CHIP_DOWN
 
 
 class DieType(Enum):
-    """Provides an enum representing die types.
-
-    - NONE
-    - FLIPCHIP
-    - WIREBOND
-    """
+    """Provides an enum representing die types."""
 
     NONE = die_property_pb2.DIE_TYPE_NONE
     FLIPCHIP = die_property_pb2.DIE_TYPE_FLIPCHIP

src/ansys/edb/core/definition/dielectric_material_model.py

@@ -8,12 +8,7 @@
 
 
 class DielectricMaterialModelType(Enum):
-    """Provides an eum representing dielectric material model types.
-
-    - DEBYE
-    - MULTIPOLE_DEBYE
-    - DJORDJECVIC_SARKAR
-    """
+    """Provides an eum representing dielectric material model types."""
 
     DEBYE = 0
     MULTIPOLE_DEBYE = 1

src/ansys/edb/core/definition/material_def.py

@@ -12,33 +12,7 @@
 
 
 class MaterialProperty(Enum):
-    """Provides an enum representing material property types.
-
-    - PERMITTIVITY
-       Permittivity property.
-    - PERMEABILITY
-       Permeability property.
-    - CONDUCTIVITY
-       Conductivity property.
-    - DIELECTRIC_LOSS_TANGENT
-       Dielectric loss tangent property.
-    - MAGNETIC_LOSS_TANGENT
-       Magnetic loss tangent property.
-    - THERMAL_CONDUCTIVITY
-       Thermal conductivity property.
-    - MASS_DENSITY
-       Mass density property.
-    - SPECIFIC_HEAT
-       Specific heat property.
-    - YOUNGS_MODULUS
-       Young's modulus property.
-    - POISSONS_RATIO
-       Poisson's ratio property.
-    - THERMAL_EXPANSION_COEFFICIENT
-       Thermal expansion coefficient property.
-    - INVALID_PROPERTY
-       Invalid property.
-    """
+    """Provides an enum representing material property types."""
 
     PERMITTIVITY = pb.PERMITTIVITY
     PERMEABILITY = pb.PERMEABILITY

src/ansys/edb/core/definition/padstack_def_data.py

@@ -148,19 +148,7 @@ def padstack_def_data_set_solder_ball_material_message(target, material):
 
 
 class PadType(Enum):
-    """Provides an enum representing pad types.
-
-    - REGULAR_PAD
-        Regular pad.
-    - ANTI_PAD
-        Anti pad.
-    - THERMAL_PAD
-         Thermal pad.
-    - HOLE
-        Hole.
-    - UNKNOWN_GEOM_TYPE
-        Undefined pad type.
-    """
+    """Provides an enum representing pad types."""
 
     REGULAR_PAD = pb.REGULAR_PAD
     ANTI_PAD = pb.ANTI_PAD
@@ -170,35 +158,7 @@ class PadType(Enum):
 
 
 class PadGeometryType(Enum):
-    """Provides an enum representing pad geometry types.
-
-    - PADGEOMTYPE_NO_GEOMETRY
-        No geometry.
-    - PADGEOMTYPE_CIRCLE
-        Circle shape.
-    - PADGEOMTYPE_SQUARE
-        Square shape.
-    - PADGEOMTYPE_RECTANGLE
-        Rectangle shape.
-    - PADGEOMTYPE_OVAL
-        Oval shape.
-    - PADGEOMTYPE_BULLET
-        Bullet shape.
-    - PADGEOMTYPE_NSIDED_POLYGON
-        N-sided polygon shape.
-    - PADGEOMTYPE_POLYGON
-        Polygonal shape.
-    - PADGEOMTYPE_ROUND45
-        Round gap with 45-degree thermal ties.
-    - PADGEOMTYPE_ROUND90
-        Round gap with 90-degree thermal ties.
-    - PADGEOMTYPE_SQUARE45
-        Square gap with 45-degree thermal ties.
-    - PADGEOMTYPE_SQUARE90
-        Square gap with 90-degree thermal ties.
-    - PADGEOMTYPE_INVALID_GEOMETRY
-        Invalid geometry.
-    """
+    """Provides an enum representing pad geometry types."""
 
     PADGEOMTYPE_NO_GEOMETRY = pb.PADGEOMTYPE_NO_GEOMETRY
     PADGEOMTYPE_CIRCLE = pb.PADGEOMTYPE_CIRCLE
@@ -216,19 +176,7 @@ class PadGeometryType(Enum):
 
 
 class PadstackHoleRange(Enum):
-    """Provides an enum representing pad hole ranges.
-
-    - THROUGH
-        Hole through all layers of the board.
-    - BEGIN_ON_UPPER_PAD
-        Hole from the upper pad to the bottom of the board.
-    - END_ON_LOWER_PAD
-        Hole from the top of the board to the lower pad.
-    - UPPER_PAD_TO_LOWER_PAD
-        Hole from the upper pad to the lower pad.
-    - UNKNOWN_RANGE
-        Undefined hole range.
-    """
+    """Provides an enum representing pad hole ranges."""
 
     THROUGH = pb.THROUGH
     BEGIN_ON_UPPER_PAD = pb.BEGIN_ON_UPPER_PAD
@@ -238,17 +186,7 @@ class PadstackHoleRange(Enum):
 
 
 class SolderballShape(Enum):
-    """Provides an enum representing solder ball shapes.
-
-    - NO_SOLDERBALL
-        No solder ball.
-    - SOLDERBALL_CYLINDER
-        Cylinder solder ball.
-    - SOLDERBALL_SPHEROID
-        Spheroid solder ball.
-    - UNKNOWN_SOLDERBALL_SHAPE
-        Undefined solder ball shape.
-    """
+    """Provides an enum representing solder ball shapes."""
 
     NO_SOLDERBALL = pb.NO_SOLDERBALL
     SOLDERBALL_CYLINDER = pb.SOLDERBALL_CYLINDER
@@ -257,15 +195,7 @@ class SolderballShape(Enum):
 
 
 class SolderballPlacement(Enum):
-    """Provides an enum representing solder ball placement.
-
-    - ABOVE_PADSTACK
-        Solder ball is placed above the padstack.
-    - BELOW_PADSTACK
-        Solder ball is placed below the padstack.
-    - UNKNOWN_PLACEMENT
-        Undefined solder ball placement type.
-    """
+    """Provides an enum representing solder ball placement."""
 
     ABOVE_PADSTACK = pb.ABOVE_PADSTACK
     BELOW_PADSTACK = pb.BELOW_PADSTACK