FIX: documentation build workflow (#7)

* MAINT: update ignore files

* DOC: fix README.md file

* REFACT: add log to check_pandoc_install

* FIX: import paths

* CI: update documentation build workflow

* MAINT: add pypandoc in doc deps

* CI: uninstall pypandoc during doc build

* DOC: rework conf.py file

* DOC: update pdf file name in make.bat

.github/workflows/ci_cd.yml

@@ -60,20 +60,23 @@ jobs:
       - name: Install project and documentation dependencies
         run: |
           .venv\Scripts\Activate.ps1
-          pip install -r requirements\requirements.txt
-          pip install -r requirements\requirements_doc.txt
+          pip install .
+          pip install .[doc]
 
-      - name: Uninstall packages and install CI dependencies
+      - name: Uninstall conflicting CI packages
         run: |
           .venv\Scripts\Activate.ps1
-          pip uninstall vtk -y
-          pip install --extra-index-url https://wheels.vtk.org -r requirements\requirements_doc_ci.txt
+          pip uninstall vtk pypandoc -y
+
+      - name: Install CI related dependencies
+        run: |
+          .venv\Scripts\Activate.ps1
+          pip install --extra-index-url https://wheels.vtk.org .[ci]
 
       - name: Create HTML documentation
         run: |
           .venv\Scripts\Activate.ps1
-          cd doc
-          .\make.bat html
+          . .\doc\make.bat html
 
       - name: Upload HTML documentation artifact
         uses: actions/upload-artifact@v3
@@ -82,18 +85,10 @@ jobs:
           path: doc/_build/html
           retention-days: 7
 
-      - name: Create PDF documentation
-        run: |
-          .venv\Scripts\Activate.ps1
-          cd doc
-          .\doc\make.bat pdf
-
-      - name: Upload HTML documentation artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: documentation-html-edb
-          path: doc/_build/html/EDBAPI
-          retention-days: 7
+      # - name: Create PDF documentation
+      #   run: |
+      #     .venv\Scripts\Activate.ps1
+      #     . .\doc\make.bat pdf
 
 #      - name: Upload PDF documentation artifact
 #        uses: actions/upload-artifact@v3

.gitignore

@@ -47,7 +47,8 @@ coverage.xml
 *.pot
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
+doc/source/api/
 log.txt
 
 python/dcp.egg-info/
@@ -109,3 +110,6 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+
+# Generated example
+src/ansys/pyaedt/examples/simple_example.py

README.md

@@ -2,40 +2,37 @@
 
 This repository holds examples for PyAEDT.
 
-# ## Code Style
-#
-# Code style can be checked by running:
+## Code Style
+
+Code style can be checked by running:
 
 ```
     tox -e style
 ```
 
-Previous command will run `pre-commit`_ for checking code quality.
+Previous command will run [pre-commit](https://pre-commit.com/) for checking code quality.
+
 
+## Documentation
 
-# ## Documentation
-#
-# Documentation can be rendered by running:
+Documentation can be rendered by running:
 
-Windows
+### Windows
 
 ```
-    tox -e doc-win
+    TODO
 ```
 
-MacOS/Linux (requires make)
+### MacOS/Linux (requires make)
 
 ```
-    tox -e doc-linux
+    TODO
 ```
 
 The resultant HTML files can be inspected using your favorite web browser:
 
 ```
-    <browser> .tox/doc_out_html/index.html
+    <browser> TODO
 ```
 
 Previous will open the rendered documentation in the desired browser.
-
-.. LINKS AND REFERENCES
-.. _pre-commit: https://pre-commit.com/

doc/make.bat

@@ -47,7 +47,7 @@ goto end
 cd "%BUILDDIR%\latex"
 for %%f in (*.tex) do (
 pdflatex "%%f" --interaction=nonstopmode)
-if NOT EXIST pyaedt.pdf (
+if NOT EXIST pyaedt-examples.pdf (
 	Echo "no pdf generated!"
 	exit /b 1)
 Echo "pdf generated!"

doc/source/conf.py

@@ -13,6 +13,8 @@
 import sys
 import warnings
 
+from ansys.pyaedt.examples import __version__
+
 # from sphinx_gallery.sorting import FileNameSortKey
 from ansys_sphinx_theme import (
     ansys_favicon,
@@ -28,32 +30,12 @@
 import numpy as np
 import pyvista
 from sphinx import addnodes
-
-# <-----------------Override the sphinx pdf builder---------------->
-# Some pages do not render properly as per the expected Sphinx LaTeX PDF signature.
-# This issue can be resolved by migrating to the autoapi format.
-# Additionally, when documenting images in formats other than the supported ones,
-# make sure to specify their types.
 from sphinx.builders.latex import LaTeXBuilder
 from sphinx.util import logging
 
 LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml", "image/webp"]
 
-from docutils.nodes import Element
-from sphinx.writers.latex import CR, LaTeXTranslator
-
-
-def visit_desc_content(self, node: Element) -> None:
-    self.body.append(CR + r"\pysigstopsignatures")
-    self.in_desc_signature = False
-
-
-LaTeXTranslator.visit_desc_content = visit_desc_content
-
-# <----------------- End of sphinx pdf builder override---------------->
-
 logger = logging.getLogger(__name__)
-
 path = pathlib.Path(__file__).parent.parent.parent / "examples"
 EXAMPLES_DIRECTORY = path.resolve()
 
@@ -221,7 +203,7 @@ def check_example_error(app, pagename, templatename, context, doctree):
 def check_build_finished_without_error(app, exception):
     """Check that no error is detected along the documentation build process."""
     if app.builder.config.html_context.get("build_error", False):
-        raise Exception("Build failed due to error in html-page-context")
+        raise Exception("Build failed due to an error in html-page-context")
 
 
 def check_pandoc_installed(app):
@@ -232,7 +214,9 @@ def check_pandoc_installed(app):
         pandoc_path = pypandoc.get_pandoc_path()
         pandoc_dir = os.path.dirname(pandoc_path)
         if pandoc_dir not in os.environ["PATH"].split(os.pathsep):
+            logger.info("Pandoc directory is not in $PATH.")
             os.environ["PATH"] += os.pathsep + pandoc_dir
+            logger.info(f"Pandoc directory '{pandoc_dir}' has been added to $PATH")
     except OSError:
         logger.error("Pandoc was not found, please add it to your path or install pypandoc-binary")
 
@@ -263,7 +247,7 @@ def setup(app):
 
 from pyaedt import is_windows
 
-project = "PyAEDT"
+project = "pyaedt-examples"
 copyright = f"(c) {datetime.datetime.now().year} ANSYS, Inc. All rights reserved"
 author = "Ansys Inc."
 cname = os.getenv("DOCUMENTATION_CNAME", "nocname.com")
@@ -584,8 +568,8 @@ def setup(app):
 latex_documents = [
     (
         master_doc,
-        f"{project}-Documentation-{__version__}.tex",
-        f"{project} Documentation",
+        f"{project}.tex",
+        f"{project} documentation",
         author,
         "manual",
     ),

examples/00-EDB/00_EDB_Create_VIA.py

@@ -12,8 +12,8 @@
 import os
 import tempfile
 
+from ansys.pyaedt.examples.constants import EDB_VERSION
 import pyaedt
-from src.ansys.pyaedt.examples.constants import EDB_VERSION
 
 temp_dir = tempfile.TemporaryDirectory(suffix=".ansys")
 aedb_path = os.path.join(temp_dir.name, "create_via.aedb")

pyproject.toml

@@ -47,7 +47,6 @@ doc = [
     "numpydoc==1.6.0",
     "osmnx",
     "pytest-sphinx==0.5.0",
-    "vtk==9.2.6",
     "pyvista==0.42.2",
     "recommonmark==0.7.1",
     "scikit-learn==1.3.1",
@@ -63,6 +62,8 @@ doc = [
     "openpyxl==3.1.2",
     "sphinx_design",
     "sphinx_jinja",
+    "vtk==9.2.6",
+    "pypandoc",
 ]
 ci = [
     "vtk-osmesa==9.2.20230527.dev0",

src/ansys/pyaedt/examples/constants.py

@@ -57,7 +57,7 @@
 import os
 import tempfile
 
-from src.ansys.pyaedt.examples.constants import EDB_VERSION
+from ansys.pyaedt.examples.constants import EDB_VERSION
 from pyaedt import Edb
 # -"""