Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.39%. Comparing base (cd5b068) to head (9bc3937).

@@ Coverage Diff @@
## main #293 +/- ##
=======================================
 Coverage 94.39% 94.39% 
=======================================
 Files 47 47 
 Lines 9686 9686 
=======================================
 Hits 9143 9143 
 Misses 543 543 

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

One more thing I forgot to mention: it looks like the lint CI action and two of the pre-commit-hooks actions are failing. This likely means you don't have pre-commit installed yet, as that would have prevented you from committing. The easiest way to get it set up is to follow the steps in CONTRIBUTING.md. Those hooks should check for issues and automatically adjust formatting to align your changes with the project's style. 😃

Hi @camUrban, thanks for the thorough review! I've addressed all the inline comments and pushed the fixes:

• R3: Removed hard line wrapping in docs/website/tutorials/getting_started.md.
• R7: Moved the literalinclude block to the end of the file.
• R18: Removed the duplicate install step.
• R23: Removed the redundant list item.
• R32: Fixed the class structure wording in the notebook.
• R9: Moved the tutorials section before examples in docs/website/README.md.
• R19: Used the actual solver class name (SteadyHorseshoeVortexLatticeMethodSolver) and added a step 8 for saving/loading results.
• R523: Removed images and execution metadata from the notebook.

Also:

• Added TianHeng Zhuang (TianHengZhuang) to the README contributors list.
• Rewrote the PR description to follow the pull request template.
• Ran codespell, black, end-of-files, mixed-line-endings, and ascii-only checks locally - all pass.
• Changed the ipynb lexer to json in conf.py to fix the RTD build warning.

Could you please take another look when you have a moment? Re-requesting review now. Thanks!

Just pushed a small fix: restored docs/website/tutorials.md with LF line endings (it was accidentally removed in a prior commit). The lint CI / pre-commit workflows are currently waiting for approval (action_required) before they can run — could you approve them so the checks re-run? Thanks!

Hey @TianHengZhuang! I'm about to post specific review comments, but decided to first push a change to your branch, which changes how the notebook is rendered and adds a script that stores its outputs. Please pull before editing. The workflow for any notebook change is now: edit, run python scripts/execute_tutorials.py, then commit the notebook and any file it wrote. The script needs the packages in requirements_dev.txt.

By the way, don't worry about the Read the Docs check showing as failed. The build didn't get past fetching the SciPy intersphinx inventory because docs.scipy.org is shakey at the moment. It will pass once SciPy's docs are back and the build is retried.

In the meantime, please check the site locally after each change. From the repository root, with your virtual environment active:

pip install -r docs/website/requirements_docs.txt
sphinx-build -W --keep-going -b html docs/website docs/website/_build/html

Then open docs/website/_build/html/tutorials/getting_started.html in a browser. The -W flag matches the Read the Docs configuration, so a clean local build means the hosted one will pass too. While docs.scipy.org is down, the local build fails with the same intersphinx warning, so if that is the only warning in the output, your changes are fine.

Thanks for the review, @camUrban! I've pushed a new commit that addresses all documentation comments:

• Reordered sections in getting_started.md so the notebook appears at the end
• Removed the redundant solvers list paragraph that duplicated the notebook content
• Unwrapped hard-wrapped paragraphs in both getting_started.md and utorials.md
• Moved tutorials before examples in the docs toctree

The notebook content fixes from the previous commit are also in place. Ready for your review whenever you have time!

Thanks for the detailed review! I've pushed a new commit (2d7966f) addressing all the documentation comments in docs/website/tutorials/getting_started.md, docs/website/tutorials.md, and docs/website/README.md, plus the inline notebook fixes in the previous commit (c593da9).

Since the inline review comments can only be marked as resolved by the comment author via the GitHub UI, could you mark each one as resolved when you have a moment, or simply approve the PR if everything looks good? Either way works for me - I just want to make sure I'm not missing anything.

Hi @TianHengZhuang. Thanks for taking the time to look over my comments. Unfortunately, it looks like you force-pushed over my changes. Thankfully, I still had a local copy, so I was able to re-push them (with your edits merged in).

Important

Please don't force push unless you are certain why a push is failing. If git push ever fails unexpectedly, never git push --force, as that often deletes someone else's work.

Instead, get in the habit of running git pull before you make changes. Then, after you make your edits, git commit and git push. No worries, it happens, but just something to keep in mind going forward.

Review Comments

Thanks for letting me know that you can't resolve comments. I didn't know that!

I've resolved the comments that you fixed. However, there are still eight that need to be taken care of. Let me know if you have any further questions. And, one last reminder, please git pull before you start! 😊

Editing the Notebook

The notebook is now rendered on the documentation site from the outputs stored in the file, so there are a couple of extra steps after editing it:

1. Edit the notebook however you like, in Jupyter or a text editor. Don't worry about outputs or execution counts, since the next step regenerates them.

2. Run the execution script from the repository root with your virtual environment active:

   pip install -r requirements.txt -r requirements_dev.txt
   python scripts/execute_tutorials.py

   It runs the notebook top to bottom, stores the outputs, and strips the metadata that shouldn't be committed. If it reports a failure, fix the cell it names and run it again.

3. Commit tutorials/getting_started.ipynb together with any file the notebook writes next to itself, such as the WebP render. The *.psz file is gitignored and stays out.

   One rule the script enforces: images are saved to files and embedded from markdown cells, never displayed inline. An inline image would be stored as base64 text in the notebook, and the script refuses to write that.

Checking Your Work on the RTD Website

Every push builds a preview of the documentation site. Click on the "docs/readthedocs.org:pterasoftware" check at the bottom of this PR, and open Tutorials in the sidebar. That is exactly what readers will see, rendered from your stored outputs, so it's the best way to check a change. You can also build it locally:

pip install -r docs/website/requirements_docs.txt
sphinx-build -W --keep-going -b html docs/website docs/website/_build/html

and open docs/website/_build/html/tutorials/getting_started.html.