Please update the examples to use Jupytext

[Devin-Crawford]

📝 Description of the feature

Jupytext allows publication
of Jupyter Notebooks in pure Python. It is much easier for users to modify/update and document examples since they can edit and modify the examples in an
WYSIWYG environment.

💡 Steps for implementing the feature

Update the GitHub Actions and dependencies to support Jupytext. Use the PyAEDT examples
workflow
and dependencies
as a reference.

🔗 Useful links and references

See the PyAEDT Examples repository.

[RobPasMue]

Hi @Devin-Crawford - at the end of all workflows you have the option to download it as a Jupyter notebook. See

The concept we are using is the same as in PyAEDT examples. There is no difference.

[RobPasMue]

For example:

Take https://github.com/ansys/pyaedt-examples/blob/main/examples/high_frequency/multiphysics/microwave_oven.py and https://github.com/ansys/pyansys-workflows/blob/main/fluent-mechanical/wf_fm_01_fluent.py

The source code are both Python files. On the build documentation, you also get the jupyter notebooks.

[Devin-Crawford]

@RobPasMue I refer in this request to the contribution and not the download. It will be easier for non developers to contribute examples if they can edit and push changes directly as a Jupyter notebook (formatted as *.py).

[RobPasMue]

Gotcha - but I still don't see the difference.

Users can use jupytext if they want to develop their examples from a Jupyter Notebook and convert them into a Python file. We would then commit the Python file to the repository. Certain headers might change, as well as line/section separators but it should be very straight forward to modify them (if even needed - which I am not sure). My feeling is that this repo could just consume those python files (as they are) and they would render just fine

[SMoraisAnsys]

@RobPasMue It seems that a lot of non developers tend to leverage Jupyter Lab to perform POCs and run examples. I agree that your approach is working fine but I think that what @Devin-Crawford wants is to be able to play with an example, edit it, and version the modifications right away.

Having an example formatted in such a way that it is both compatible with jupytext using the light format and can be rendered and run in Jupyter Lab as Notebook files is really great because we can easily use them for our documentation and even execute them as python file. I think it would be a great change for non developers.

[RobPasMue]

Hi @SMoraisAnsys @Devin-Crawford

1. I completely understand the need for a Jupyter environment to test things out and develop POCs. I am 100% willing to support that
2. What prevents a user from downloading the current example in .ipynb format from the docs, do their edits, and then export it to the final repository's format which is .py using jupytext?

I might be missing something but I currently see no issues in the process -- we just need to give them the right command to export it into the format used in this repository or any other repository (depending on how each repository handles their examples). IMO this is more of a "documentation" request rather than actual tooling request.

[SMoraisAnsys]

The main target aren't specifically users here (while it would also be good for them to have a single point of source to run things from Python or Jupyter Lab) but application engineer creating examples. Having a single file to work with would greatly help to maintain examples as they could be edited from Jupyter Lab / VSCode / Notepad and then commited + pushed to github.

[RobPasMue]

But in that case you are suggesting to work directly on the Python file, right?

[RobPasMue]

A Python file is not a Jupyter NB. Even though IDEs like VSCode or others could open it like that. If you want to develop on a Jupyter NB you should work on a ipynb file and then convert it to py using jupytext. If you want to work on the py file directly, I wouldn't expect it to behave as a Jupyter NB (even if some editors make it look like it)..