Doc/jupyter examples #4144

Devin-Crawford · 2024-01-28T23:25:35Z

Test jupytext examples.

Enable Jupytext.

Move readme.txt to index.rst

ansys-reviewer-bot · 2024-01-28T23:25:38Z

Thanks for opening a Pull Request. If you want to perform a review write a comment saying:

@ansys-reviewer-bot review

Move readme.txt to index.rst

codecov · 2024-01-28T23:54:15Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (7fe1146) 82.10% compared to head (e11b4f4) 31.00%.

❗ Current head e11b4f4 differs from pull request most recent head 370005b. Consider uploading reports for the commit 370005b to get more accurate results

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #4144       +/-   ##
===========================================
- Coverage   82.10%   31.00%   -51.10%     
===========================================
  Files         183      183               
  Lines       64464    64464               
===========================================
- Hits        52927    19989    -32938     
- Misses      11537    44475    +32938

Note: The current workflow to build documentation does not show something clear in the CI if an example contains an error. It only fails without much information. It would be nice to add a way to display the issue in the CI.

SMoraisAnsys · 2024-01-29T13:03:21Z

@dcrawforAtAnsys The previous problem has been fixed and the new one seems to be that pandoc is not installed.

I'll let you handle that (unless you can't access our runners) and focus on extending the current CI workflow. Indeed, I struggled a lot (for nothing) to make the documentation work back on track as we are not able ton retrieve any information about the reason the CI was failing. In this case, it was failing because of a code typo (resulting in an exception) and the problem should have been solved fast. I expect that to be a blocking point for future collaborators wanting to add new examples or simply to modify existing ones.

Btw, since you created a new PR, I suppose we should close #3940 and #4064 right ?

PipKat · 2024-01-29T20:07:46Z

doc/source/conf.py

+# Sphinx event hooks
+
+def directory_size(directory_path):
+    """Compute the size (in mega bytes) of a directory."""


Suggested change

"""Compute the size (in mega bytes) of a directory."""

"""Compute the directory size in megabytes."""

PipKat · 2024-01-29T20:08:14Z

doc/source/conf.py

+        for f in files:
+            fp = os.path.join(path, f)
+            res += os.stat(fp).st_size
+    # Convert in mega bytes


Suggested change

# Convert in mega bytes

# Convert in megabytes

PipKat · 2024-01-29T20:18:29Z

doc/source/conf.py

+    logger.info(f"Doctree removed.")
+
+def copy_examples(app):
+    """Copy directory examples (root directory) files into the doc/source/examples directory.


Suggested change

"""Copy directory examples (root directory) files into the doc/source/examples directory.

"""Copy directory examples from the root directory into the ``doc/source/examples`` directory.

PipKat · 2024-01-29T20:18:50Z

doc/source/conf.py

+    logger.info(f"Copying examples from {EXAMPLES_DIRECTORY} to {DESTINATION_DIRECTORY}.")
+    if os.path.exists(DESTINATION_DIRECTORY):
+        size = directory_size(DESTINATION_DIRECTORY)
+        logger.info(f"Directory {DESTINATION_DIRECTORY} ({size} MB) already exist, removing it.")


Suggested change

logger.info(f"Directory {DESTINATION_DIRECTORY} ({size} MB) already exist, removing it.")

logger.info(f"Directory {DESTINATION_DIRECTORY} ({size} MB) already exists. Removing it.")

PipKat · 2024-01-29T20:19:00Z

doc/source/conf.py

+        logger.info(f"Directory removed.")
+
+    shutil.copytree(EXAMPLES_DIRECTORY, DESTINATION_DIRECTORY)
+    logger.info(f"Copy performed")


Suggested change

logger.info(f"Copy performed")

logger.info(f"Copy performed.")

PipKat · 2024-01-29T20:19:11Z

doc/source/conf.py

+    logger.info(f"Copy performed")
+
+def remove_examples(app, exception):
+    """Remove the doc/source/examples directory created during the documentation build.


Suggested change

"""Remove the doc/source/examples directory created during the documentation build.

"""Remove the ``doc/source/examples`` directory created during the documentation build.

PipKat · 2024-01-29T20:19:32Z

doc/source/conf.py

+    logger.info(f"Directory removed.")
+
+def add_ipython_time(app, docname, source):
+    """Add '# %%time' to every code cell in an example Python script.


Suggested change

"""Add '# %%time' to every code cell in an example Python script.

"""Add ``# %%time`` to every code cell in an example Python script.

PipKat · 2024-01-29T20:20:28Z

doc/source/conf.py

+    # <img src="../../doc/source/_static/diff_via.png" width="500">
+    However, examples fail when used through the documentation build because
+    reaching the associated path should be "../../_static/diff_via.png".
+    Indeed, the directory ``_static`` is automatically copied into the output directory


Suggested change

Indeed, the directory ``_static`` is automatically copied into the output directory

Indeed, the ``_static`` directory is automatically copied into the

PipKat · 2024-01-29T20:20:46Z

doc/source/conf.py

+    However, examples fail when used through the documentation build because
+    reaching the associated path should be "../../_static/diff_via.png".
+    Indeed, the directory ``_static`` is automatically copied into the output directory
+    ``_build/html/_static``.


Suggested change

``_build/html/_static``.

``_build/html/_static`` output directory.

Nouns should follow code entity tags.

PipKat · 2024-01-29T20:21:08Z

doc/source/conf.py

+    source[0] = source[0].replace('../../doc/source/_static', '../../_static')
+
+def remove_ipython_time_from_html(app, pagename, templatename, context, doctree):
+    """Remove '# %%time' from examples generated HTML files.


Suggested change

"""Remove '# %%time' from examples generated HTML files.

"""Remove ``# %%time`` from examples generated HTML files.

Misisng word between "generated" and "HTML".

PipKat · 2024-01-29T20:22:02Z

doc/source/conf.py

+    """Remove '# %%time' from examples generated HTML files.
+    """
+    if pagename.startswith("examples") and not pagename.endswith("/index"):
+        logger.info(f"Removing '# %%time' from file {pagename}")


Suggested change

logger.info(f"Removing '# %%time' from file {pagename}")

logger.info(f"Removing '# %%time' from file {pagename}.")

examples/00-EDB/00_EDB_Create_VIA.py

PipKat · 2024-01-29T20:25:43Z

examples/00-EDB/01_edb_example.py

+This example demonstrates the use of EDB to interact with a PCB
+layout and run DC-IR analysis in SIwave.


Suggested change

This example demonstrates the use of EDB to interact with a PCB

layout and run DC-IR analysis in SIwave.

This example shows how to use EDB to interact with a PCB

layout and run a DC-IR analysis in SIwave.

examples/00-EDB/01_edb_example.py

…upyter_examples

Remove 01-RC_Circuit_Example.py as the same content is covered by 02-Wiring_A_Rectifier.py

Clean up formatting and readability. Move some images to the local examples _static folder.

SMoraisAnsys

I'm just adding this comment to remember that we need to clean the PR later on.
A lot as been done to remove extra checks wrt CI/CD and documentation to focus on examples.

Notes: since we need pandoc during the creation of the examples' documentation, we need to ensure that it is available every time. This should avoid us to install it on every self hosted rnner

codecov-commenter · 2024-02-07T15:30:32Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (82f373a) 82.01% compared to head (e11b4f4) 31.00%.
Report is 1 commits behind head on main.

❗ Current head e11b4f4 differs from pull request most recent head c2fbe49. Consider uploading reports for the commit c2fbe49 to get more accurate results

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #4144       +/-   ##
===========================================
- Coverage   82.01%   31.00%   -51.01%     
===========================================
  Files         183      183               
  Lines       64727    64464      -263     
===========================================
- Hits        53083    19989    -33094     
- Misses      11644    44475    +32831

SMoraisAnsys · 2024-02-23T10:36:29Z

Closing this PR as we re moving the examples into another repo.

Devin-Crawford added 3 commits January 28, 2024 16:45

Update examples

2a28551

Enable Jupytext.

Update css

7fd355c

Update Example directories

a9a8f30

Move readme.txt to index.rst

github-actions bot added documentation maintenance Package and maintenance related labels Jan 28, 2024

Update Example directories

d5afc27

Move readme.txt to index.rst

Devin-Crawford requested a review from SMoraisAnsys January 29, 2024 01:27

DOC: fix EDB in 3D layout example

8da4fbe

Note: The current workflow to build documentation does not show something clear in the CI if an example contains an error. It only fails without much information. It would be nice to add a way to display the issue in the CI.