ci: add pandoc to dependencies for doc build

.github/workflows/ci_cd_pr.yml

@@ -133,6 +133,7 @@ jobs:
           skip-install: true
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
           use-python-cache: false
+          dependencies: "pandoc"
           needs-quarto: true
 
   doc-deploy-pr:

doc/source/changelog/19.maintenance.md

@@ -0,0 +1 @@
+Add pandoc to dependencies for doc build

doc/source/conf.py

@@ -2,6 +2,8 @@
 
 from datetime import datetime
 import os
+import pathlib
+import shutil
 
 from ansys_sphinx_theme import get_version_match
 
@@ -49,6 +51,7 @@
     "sphinx_copybutton",
     "sphinx_design",  # Needed for cards
     "sphinx.ext.extlinks",
+    "nbsphinx",
 ]
 
 # Intersphinx mapping
@@ -90,14 +93,75 @@
 copybutton_prompt_text = r">>> ?|\.\.\. ?"
 copybutton_prompt_is_regexp = True
 
+# Ignore files for build
+
+exclude_patterns = ["conf.py", "examples/README.rst"]
+
 
 # Skipping members
 def autodoc_skip_member_custom(app, what, name, obj, skip, options):
     """Skip members that are not intended to be in documentation."""
     return True if obj.__doc__ is None else None  # need to return none if exclude is false otherwise it will interfere with other skip functions
 
 
-# RST prolog for substitution of custom variables
+# nbpsphinx configurations
+
+nbsphinx_execute = "never"
+
+nbsphinx_custom_formats = {".py": ["jupytext.reads", {"fmt": ""}]}
+
+nbsphinx_prolog = """
+
+
+.. grid:: 1 2 2 2
+
+    .. grid-item::
+
+        .. button-link:: {base_path}/{ipynb_file_path}
+            :color: secondary
+            :shadow:
+            :align: center
+
+            :octicon:`download` Download Jupyter Notebook (.ipynb)
+
+
+    .. grid-item::
+
+        .. button-link:: {base_path}/{py_file_path}
+            :color: secondary
+            :shadow:
+            :align: center
+
+            :octicon:`download` Download Python script (.py)
+
+----
+""".format(
+    base_path=f"https://{cname}/version/{get_version_match(version)}", py_file_path="{{ env.docname }}.py", ipynb_file_path="{{ env.docname }}.ipynb"
+)
+
+# Define auxiliary functions needed for examples
+
+
+def copy_examples_to_source_dir(app):
+    """Copy examples to source directory for nbsphinx."""
+    source_dir = pathlib.Path(app.srcdir)
+
+    shutil.copytree(source_dir.parent.parent / "examples", source_dir / "examples", dirs_exist_ok=True)
+
+
+def remove_examples_from_source_dir(app, exception):
+    """Remove examples from source directory after build."""
+    source_dir = pathlib.Path(app.srcdir)
+    shutil.rmtree(source_dir / "examples")
+
+
+def copy_examples_to_output_dir(app, exception):
+    """Copy examples to output directory."""
+    source_dir = pathlib.Path(app.srcdir)
+    build_dir = pathlib.Path(app.outdir)
+
+    shutil.copytree(source_dir.parent.parent / "examples", build_dir / "examples", dirs_exist_ok=True)
+
 
 rst_prolog = ""
 
@@ -133,6 +197,12 @@ def autodoc_skip_member_custom(app, what, name, obj, skip, options):
 extlinks = {"examples_url": (f"{html_theme_options['github_url']}/blob/main/examples/%s", "%s")}
 
 
+# Define setup function
+
+
 def setup(app):
     """Sphinx setup function."""
+    app.connect("builder-inited", copy_examples_to_source_dir)
     app.connect("autodoc-skip-member", autodoc_skip_member_custom)
+    app.connect("build-finished", remove_examples_from_source_dir)
+    app.connect("build-finished", copy_examples_to_output_dir)

doc/source/examples.rst

@@ -5,24 +5,41 @@ You can use the examples below to get started with PyLumerical and learn its bas
 
 For in-depth discussion of PyLumerical concepts, see the :doc:`User guide <user_guide/index>`.
 
-.. grid:: 2 2 3 3
+.. grid:: 2 2 4 4
 
    .. grid-item-card:: Session management
+      :link: examples/Sessions_and_Objects/basic_session_management
+      :link-type: doc
 
       This example demonstrates how to initialize a local Lumerical session using PyLumerical.
 
-      Download the example :examples_url:`here <Sessions_and_Objects/basic_session_management.py>`.
-
    .. grid-item-card:: Basic FDTD simulation - Lumerical style commands
+      :link: examples/Sessions_and_Objects/fdtd_example1_lsf
+      :link-type: doc
 
       This example demonstrates how to set up a basic FDTD simulation with a Gaussian source and frequency-domain monitor.
       The example uses PyLumerical with workflows and syntax similar to the Lumerical Scripting Language.
 
-      Download the example :examples_url:`here <Sessions_and_Objects/fdtd_example1_lsf.py>`.
 
    .. grid-item-card:: Basic FDTD simulation - Python style commands
+      :link: examples/Sessions_and_Objects/fdtd_example1_pythonic
+      :link-type: doc
 
       This example demonstrates how to set up a basic FDTD simulation with a Gaussian source and frequency-domain monitor.
       This example uses PyLumerical with workflows and syntax that is more native to Python.
 
-      Download the example :examples_url:`here <Sessions_and_Objects/fdtd_example1_pythonic.py>`.
+   .. grid-item-card:: FDE MODE Simulation
+      :link: examples/Sessions_and_Objects/waveguide_FDE
+      :link-type: doc
+
+      This example demonstrates how to set up a basic simulation with Ansys Lumerical MODE™ using the FDE solver.
+
+
+
+.. toctree::
+   :hidden:
+
+   examples/Sessions_and_Objects/basic_session_management
+   examples/Sessions_and_Objects/fdtd_example1_lsf
+   examples/Sessions_and_Objects/fdtd_example1_pythonic
+   examples/Sessions_and_Objects/waveguide_FDE

doc/styles/config/vocabularies/ANSYS/accept.txt

@@ -29,4 +29,5 @@ photonic
 photonics
 lumopt
 lumslurm
-[Aa]utodiscovery
+[Jj]upytext
+[Aa]utodiscovery

examples/README.rst

@@ -0,0 +1,17 @@
+Examples
+========
+
+Examples source files for PyLumerical are .py files. The PyLumerical documentation infrastructure converts these .py source files into .rst files for display on the documentation site, by first converting them into Jupyter Notebooks using `Jupytext <https://jupytext.readthedocs.io/en/latest/>`_, and then converting the notebooks into .rst files using `nbsphinx <https://nbsphinx.readthedocs.io/en/latest/>`_.
+
+Formatting
+----------
+
+Example files must be compliant with `PEP8 <https://peps.python.org/pep-0008/>`_ guidelines, as listed on the PyAnsys Developer's `guide <https://dev.docs.pyansys.com/how-to/documenting.html#examples>`_.
+
+PyLumerical examples uses the "Light" format for jupytext conversion. To write comment cells into your source file, follow the formatting guidelines listed in the `Jupytext documentation <https://jupytext.readthedocs.io/en/latest/formats-scripts.html>`_.
+
+Always ensure that your example files run without errors, and are properly formatted prior to submitting a pull request.
+
+The documentation build process currently not automatically execute the examples, as such, no outputs are displayed in the resulting documentation pages.
+
+You can test your examples locally by running them as scripts, and you can test that the documentation formatting is correct by locally building the documentation. See the `contributing section <../doc/source/contributing.rst>`_ for more information.