DOCS: Rework example documentation (#43)

Co-authored-by: pyansys-ci-bot <pyansys.github.bot@ansys.com>

.github/workflows/ci_cd.yml

@@ -14,8 +14,6 @@ env:
   MEILISEARCH_API_KEY: ${{ secrets.MEILISEARCH_API_KEY }}
   MEILISEARCH_HOST_URL: ${{ vars.MEILISEARCH_HOST_URL }}
   MEILISEARCH_PUBLIC_API_KEY: ${{ secrets.MEILISEARCH_PUBLIC_API_KEY }}
-  # LIBRARY_NAME: 'ansys-conceptev-core'
-  # LIBRARY_NAMESPACE: 'ansys.conceptev.core'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -115,15 +113,15 @@ jobs:
         uses: actions/upload-artifact@v4
         if: env.MAIN_PYTHON_VERSION == matrix.python-version
         with:
-          name: coverage-tests-{{ '${{ matrix.os }}' }}
+          name: coverage-tests-${{ matrix.os }}
           path: .cov
           retention-days: 7
 
       - name: Upload coverage results (as .coverage)
         uses: actions/upload-artifact@v4
         if: env.MAIN_PYTHON_VERSION == matrix.python-version
         with:
-          name: coverage-file-tests-{{ '${{ matrix.os }}' }}
+          name: coverage-file-tests-${{ matrix.os }}
           path: .coverage
           retention-days: 7
 
@@ -132,7 +130,21 @@ jobs:
     runs-on: ubuntu-latest
     needs: [doc-style]
     steps:
-      - uses: ansys/actions/doc-build@v6
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pandoc
+          sudo apt-get install texlive-latex-extra texlive-xetex texlive-fonts-extra
+          # sudo apt-get install libgl1-mesa-glx xvfb texlive-latex-extra latexmk graphviz texlive-xetex texlive-fonts-extra qpdf texlive-xetex xindy
+
+      - name: Verify Pandoc installation
+        run: pandoc --version
+
+      - name: Build documentation
+        env:
+          CONCEPTEV_USERNAME: ${{ secrets.CONCEPTEV_USERNAME }}
+          CONCEPTEV_PASSWORD: ${{ secrets.CONCEPTEV_PASSWORD }}
+        uses: ansys/actions/doc-build@v6
         with:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
           check-links: false

.pre-commit-config.yaml

@@ -25,14 +25,14 @@ repos:
   rev: v2.2.6
   hooks:
   - id: codespell
-    args: ["--ignore-words", "doc/styles/config/vocabularies/ANSYS/accept.txt", "-w"]
+    args: ["--ignore-words", "doc/styles/config/vocabularies/ANSYS/accept.txt", "-w", "--skip=poetry.lock"]
 
 - repo: https://github.com/pycqa/pydocstyle
   rev: 6.3.0
   hooks:
   - id: pydocstyle
     additional_dependencies: [tomli]
-    exclude: "tests/"
+    exclude: "^(tests|examples)"
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0

doc/Makefile

@@ -28,5 +28,5 @@ clean:
 # Customized pdf for svg format images
 pdf:
 	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
+	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf -xelatex *.tex -interaction=nonstopmode || true
 	(test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1

doc/changelog.d/43.changed.md

@@ -0,0 +1 @@
+DOCS: Rework example documentation

doc/make.bat

@@ -42,7 +42,7 @@ goto end
 %SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 cd "%BUILDDIR%\latex"
 for %%f in (*.tex) do (
-pdflatex "%%f" --interaction=nonstopmode)
+xelatex "%%f" --interaction=nonstopmode)
 if NOT EXIST ansys-conceptev-core.pdf (
 	Echo "no pdf generated!"
 	exit /b 1)

doc/source/_static/custom.css

@@ -0,0 +1,44 @@
+@import "../ansys-sphinx-theme.css";
+
+/* Do not show number cells in notebooks */
+.nbinput .prompt,
+.nboutput .prompt {
+    display: none !important;
+}
+
+/* Ensure proper font size for notebook cells */
+.nboutput {
+    font-size: 1.1em;
+}
+
+.nbinput {
+    font-size: 1em;
+}
+
+/* Expand cell content output to the width of the notebook */
+div.nbinput.container div.input_area, div.nboutput.container div.output_area {
+    display: block;
+}
+
+/* Center images in notebook output cells */
+.nboutput img {
+    display: block !important;
+    margin: 0 auto !important;
+}
+
+.sd-card .sd-card-img-top {
+    height: 100px;
+    width: 100px;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+.sd-card .sd-card-header {
+  font-size: var(--pst-font-size-h5);
+  font-weight: bold;
+  padding: 1rem 0rem 1rem 0rem;
+}
+
+.sd-card .sd-card-footer .sd-card-text {
+  max-width: 220px;
+}

doc/source/conf.py

@@ -2,18 +2,26 @@
 
 from datetime import datetime
 import os
+import pathlib
+import shutil
 
 from ansys_sphinx_theme import get_version_match
 from ansys_sphinx_theme import pyansys_logo_black as logo
+import sphinx
+from sphinx.util import logging
 
 from ansys.conceptev.core import __version__
 
+logger = logging.getLogger(__name__)
+path = pathlib.Path(__file__).parent.parent.parent / "examples"
+EXAMPLES_DIRECTORY = path.resolve()
+
 # Project information
 project = "ansys-conceptev-core"
 copyright = f"(c) 2023-{datetime.today().year} ANSYS, Inc. and/or its affiliates."
 author = "ANSYS, Inc."
 release = version = __version__
-cname = os.getenv("DOCUMENTATION_CNAME", "docs.pyansys.com")
+cname = os.getenv("DOCUMENTATION_CNAME", "conceptev.core.docs.pyansys.com")
 switcher_version = get_version_match(__version__)
 
 # Select desired logo, theme, and declare the html title
@@ -29,7 +37,7 @@
 
 # specify the location of your github repo
 html_theme_options = {
-    "github_url": "https://github.com/pyconceptev-core",
+    "github_url": "https://github.com/ansys/pyconceptev-core",
     "use_edit_page_button": True,
     "show_prev_next": False,
     "show_breadcrumbs": True,
@@ -45,7 +53,9 @@
 
 # Sphinx extensions
 extensions = [
+    "nbsphinx",
     "numpydoc",
+    "recommonmark",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.imgconverter",
@@ -81,23 +91,124 @@
     # type, unless multiple values are being returned"
 }
 
-# static path
+# Static path
 html_static_path = ["_static"]
+html_css_files = [
+    "custom.css",
+]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "_build",
+    "*.txt",
+    "conf.py",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
-source_suffix = ".rst"
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
 
 # The master toctree document.
 master_doc = "index"
 
-linkcheck_ignore = []
+# Examples gallery customization
+nbsphinx_execute = "always"
+nbsphinx_allow_errors = False
+nbsphinx_thumbnails = {
+    "examples/simple_workflow": "_static/thumbnails/simple_workflow.png",
+}
+nbsphinx_custom_formats = {
+    ".py": ["jupytext.reads", {"fmt": ""}],
+}
+
+# Activate fontawesome icons in LaTeX
+sd_fontawesome_latex = True
+
+linkcheck_exclude_documents = ["index"]
+linkcheck_ignore = [
+    r"https://download.ansys.com/",
+    r".*/examples/.*.py",
+    r"_static/assets/.*",
+]
+
 
 # If we are on a release, we have to ignore the "release" URLs, since it is not
 # available until the release is published.
 if switcher_version != "dev":
     linkcheck_ignore.append(
         f"https://github.com/ansys/pyconceptev-core/releases/tag/v{__version__}"
     )
+
+# Sphinx event hooks
+
+
+def directory_size(directory_path):
+    """Compute the size (in mega bytes) of a directory."""
+    res = 0
+    for path, _, files in os.walk(directory_path):
+        for f in files:
+            fp = os.path.join(path, f)
+            res += os.stat(fp).st_size
+    # Convert in mega bytes
+    res /= 1e6
+    return res
+
+
+def check_pandoc_installed(app):
+    """Ensure that pandoc is installed."""
+    import pypandoc
+
+    try:
+        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")
+
+
+def copy_examples(app):
+    """Copy directory examples (root directory) files into the doc/source/examples directory."""
+    destination_dir = pathlib.Path(app.srcdir, "examples").resolve()
+    logger.info(f"Copying examples from {EXAMPLES_DIRECTORY} to {destination_dir}.")
+
+    if os.path.exists(destination_dir):
+        size = directory_size(destination_dir)
+        logger.info(f"Directory {destination_dir} ({size} MB) already exist, removing it.")
+        shutil.rmtree(destination_dir)
+        logger.info(f"Directory removed.")
+
+    shutil.copytree(EXAMPLES_DIRECTORY, destination_dir)
+    logger.info(f"Copy performed")
+
+
+def remove_examples(app, exception):
+    """Remove the doc/source/examples directory created during the documentation build."""
+    destination_dir = pathlib.Path(app.srcdir) / "examples"
+
+    size = directory_size(destination_dir)
+    logger.info(f"Removing directory {destination_dir} ({size} MB).")
+    shutil.rmtree(destination_dir, ignore_errors=True)
+    logger.info(f"Directory removed.")
+
+
+def setup(app: sphinx.application.Sphinx):
+    """Run different hook functions during the documentation build.
+
+    Parameters
+    ----------
+    app : sphinx.application.Sphinx
+        Sphinx instance containing all the configuration for the documentation build.
+    """
+    app.connect("builder-inited", copy_examples)
+    app.connect("builder-inited", check_pandoc_installed)
+    app.connect("build-finished", remove_examples)

doc/source/index.rst

@@ -31,6 +31,13 @@ of EV powertrains.
         Understand how the `Ansys ConceptEV API documentation <https://conceptev.ansys.com/api/docs>`_
         provides for interacting programmatically with PyConcept EV.
 
+    .. grid-item-card:: Examples :fa:`scroll`
+        :padding: 2 2 2 2
+        :link: examples/index
+        :link-type: doc
+
+        Explore examples that show how to use PyConcept EV.
+
     .. grid-item-card:: Contribute :material-regular:`group`
         :padding: 2 2 2 2
         :link: contributing
@@ -46,5 +53,6 @@ of EV powertrains.
    getting_started
    user_guide
    api_ref
+   examples/index
    contributing
    changelog

examples/index.rst

@@ -0,0 +1,16 @@
+Examples
+########
+
+These examples demonstrate usage of PyConcept EV.
+
+PyConcept EV examples
+---------------------
+These examples demonstrate basic operations you can perform
+with PyConcept EV.
+
+.. nbgallery::
+
+    simple_workflow.py
+
+.. note::
+    Examples require having access to https://prod.portal.onscale.com/api