Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc/jupyter examples #4144

Closed
wants to merge 63 commits into from
Closed

Doc/jupyter examples #4144

wants to merge 63 commits into from

Conversation

Devin-Crawford
Copy link
Contributor

Test jupytext examples.

@ansys-reviewer-bot
Copy link
Contributor

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

@ansys-reviewer-bot review

@github-actions github-actions bot added documentation maintenance Package and maintenance related labels Jan 28, 2024
Move readme.txt to index.rst
Copy link

codecov bot commented Jan 28, 2024

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
Copy link
Collaborator

@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 ?

# Sphinx event hooks

def directory_size(directory_path):
"""Compute the size (in mega bytes) of a directory."""
Copy link
Member

@PipKat PipKat Jan 29, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Convert in mega bytes
# Convert in megabytes

logger.info(f"Doctree removed.")

def copy_examples(app):
"""Copy directory examples (root directory) files into the doc/source/examples directory.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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.")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.")

logger.info(f"Directory removed.")

shutil.copytree(EXAMPLES_DIRECTORY, DESTINATION_DIRECTORY)
logger.info(f"Copy performed")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
logger.info(f"Copy performed")
logger.info(f"Copy performed.")

logger.info(f"Copy performed")

def remove_examples(app, exception):
"""Remove the doc/source/examples directory created during the documentation build.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

logger.info(f"Directory removed.")

def add_ipython_time(app, docname, source):
"""Add '# %%time' to every code cell in an example Python script.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

# <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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Nouns should follow code entity tags.

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.
Copy link
Member

@PipKat PipKat Jan 29, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Misisng word between "generated" and "HTML".

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines 4 to 5
This example demonstrates the use of EDB to interact with a PCB
layout and run DC-IR analysis in SIwave.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

@SMoraisAnsys SMoraisAnsys left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link

codecov-commenter commented Feb 7, 2024

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
Copy link
Collaborator

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
maintenance Package and maintenance related
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants