Improve documentation for base simulation classes #1295

ghwilliams · 2023-10-16T23:09:54Z

This is another step toward improving the documentation of the API.
This time I only worked on a single file (simulation.py).
I think that these changes make the documentation better, but by no means I consider it the best that can be done. So, it is a work in (eternal) progress.

Summary

Summary added before Squash and Merge:

Extend documentation for base simulation classes and in SyntheticData class. Fix typo and rst style in mesh_utils.py. Add pymatsolver to the list of intersphinx_mapping in Sphinx's docs/conf.py.

PR Checklist

If this is a work in progress PR, set as a Draft PR
Linted my code according to the style guides.
Added tests to verify changes to the code.
Added necessary documentation to any new functions/classes following the
expect style.
Marked as ready for review (if this is was a draft PR), and converted
to a Pull Request
Tagged @simpeg/simpeg-developers when ready for review.

Reference issue

What does this implement/fix?

Additional information

But I would like in a very near future to look closer at PDESimulation classes.

codecov · 2023-11-28T22:15:15Z

Codecov Report

Attention: Patch coverage is 87.50000% with 1 lines in your changes are missing coverage. Please review.

Project coverage is 82.37%. Comparing base (489851f) to head (c762ce9).

Files	Patch %	Lines
SimPEG/simulation.py	87.50%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1295   +/-   ##
=======================================
  Coverage   82.37%   82.37%           
=======================================
  Files         166      166           
  Lines       25379    25379           
=======================================
  Hits        20905    20905           
  Misses       4474     4474

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

santisoler

Thanks for this work @ghwilliams!

I think this is ready to be merged. I just left a few minor suggestions, mainly improving rst and LaTeX syntax in the docstrings.

Let me know what do you think.

SimPEG/data.py

SimPEG/simulation.py

ghwilliams · 2024-01-15T19:32:21Z

@santisoler @dccowan Done all the suggested changes!

Use r-string when including backslashes in the docstring. Fix syntax for the tip admonition.

…to Doc_BaseSimulations

santisoler

Hi @ghwilliams! Sorry for the delayed review of this PR. Thanks for applying the suggestions I made.

I just applied a few more that weren't resolved yet (no worries 🙂) and a some small changes to make flake8 happy. I also updated the branch against the latest changes in main and solved a few conflicts in simulation.py.

I left a little comment regarding the docstring of ExponentialSinusoidSimulation. Beside that, I think this is ready to be merged!

SimPEG/simulation.py

lheagy

Thanks so much @ghwilliams and @santisoler for your work on this pr! It is awesome to see improvements to the docs. I have just a few minor inline comments on the pr. Feel free to let me know if anything is unclear

SimPEG/simulation.py

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

SimPEG/simulation.py

SimPEG/data.py

santisoler · 2024-04-02T21:27:57Z

This is looking great @ghwilliams! Thanks again for all the effort you put into this, and thanks @lheagy for the reviews. I'll merge it after CI passes.

…al_update_21_release * commit '07aeb65de865cd9df55e2d51ca840ea9d60f2234': (67 commits) Fix rst syntax in release notes for v0.21.0 (simpeg#1434) Replace use of `refine_tree_xyz` in DCIP tutorials (simpeg#1381) Add new Issue template for making a release (simpeg#1410) Safely run reviewdog on `pull_request_target` events (simpeg#1427) Use reviewdog to annotate PR's with black and flake8 errors. (simpeg#1424) Remove the parameters argument from docstring (simpeg#1417) Add release notes for v0.21.1 (simpeg#1416) Fix hard dask dependency (simpeg#1415) Publish documentation on azure (simpeg#1412) Add release notes for SimPEG v0.21 (simpeg#1409) Bump Black version to 24.3.0 (simpeg#1403) Remove link to "twitter" (simpeg#1406) Add Ying and Williams to AUTHORS.rst (simpeg#1405) Dask MetaSim (simpeg#1199) Update year in LICENSE (simpeg#1404) Update AUTHORS.rst (simpeg#1259) Minor adjustments to Sphinx configuration (simpeg#1398) Enforce regularization `weights` as dictionaries (simpeg#1344) Improve documentation for base simulation classes (simpeg#1295) Add link to User Tutorials to navbar in docs (simpeg#1401) ... # Conflicts: # SimPEG/electromagnetics/time_domain/receivers.py # SimPEG/utils/__init__.py # SimPEG/utils/model_utils.py # tests/base/regularizations/test_full_gradient.py # tests/base/regularizations/test_regularization.py # tests/base/test_model_utils.py # tests/base/test_utils.py # tests/pf/test_forward_Mag_Linear.py

ghwilliams added 2 commits October 16, 2023 15:26

Much of the work done in simulation.py.

114bc5c

I think that it is ready for a PR.

c6da84e

But I would like in a very near future to look closer at PDESimulation classes.

dccowan self-assigned this Nov 28, 2023

Merge branch 'main' into Doc_BaseSimulations

d9a6fd7

dccowan added 5 commits November 28, 2023 16:29

start working through base simulation docstrings

a13152c

final draft docstring simulation.py

27eaaf7

fix typos in mesh_utils and data

262a6ed

bug in intersphinx to pymatsolver

323c4c2

reactivate gen gallery

7ac37b9

dccowan added ready for review documentation labels Nov 29, 2023

dccowan added this to the 0.21.0 milestone Dec 6, 2023

dccowan requested a review from a team December 6, 2023 18:50

dccowan approved these changes Dec 6, 2023

View reviewed changes

ghwilliams and others added 6 commits December 20, 2023 09:37

Correcting a few more conventions.

c30a3f8

Minor editings.

89f9337

Merge remote-tracking branch 'upstream/main' into Doc_BaseSimulations

fa2cf26

Merge branch 'main' into Doc_BaseSimulations

58af906

Merge branch 'main' into Doc_BaseSimulations

7bc2861

Merge branch 'main' into Doc_BaseSimulations

0fc2c90

santisoler requested changes Jan 11, 2024

View reviewed changes

ghwilliams added 2 commits January 13, 2024 15:34

Merge branch 'simpeg:main' into Doc_BaseSimulations

a9a2ad6

Making changes according to Santi's suggestions.

5758b8d

santisoler self-requested a review January 15, 2024 19:38

santisoler approved these changes Mar 6, 2024

View reviewed changes

santisoler self-requested a review March 6, 2024 18:25

santisoler added 2 commits March 13, 2024 10:22

Improve rst syntax on shape for jacobian

42ff18c

Mark simulation arguments as optional

7a7b1ad

santisoler added 5 commits March 13, 2024 10:23

Improve rst syntax for shape of time_steps

ba4c9d0

Improve rst syntax for shape of time_steps

744ca7f

Improve rst syntax for shape in docstring

49e3eef

Fix flake errors

31ef9c4

Use r-string when including backslashes in the docstring. Fix syntax for the tip admonition.

Merge branch 'Doc_BaseSimulations' of github.com:ghwilliams/simpeg in…

ec50ad1

…to Doc_BaseSimulations

santisoler force-pushed the Doc_BaseSimulations branch from 77731f5 to ec50ad1 Compare March 13, 2024 18:01

Merge branch 'main' into Doc_BaseSimulations

a4354de

santisoler approved these changes Mar 13, 2024

View reviewed changes

SimPEG/simulation.py Show resolved Hide resolved

lheagy reviewed Mar 23, 2024

View reviewed changes

ghwilliams and others added 9 commits March 28, 2024 16:04

Update SimPEG/simulation.py

7d637bc

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

Update SimPEG/simulation.py

65cb9f2

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

Update SimPEG/simulation.py

81e6a7c

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

Update SimPEG/simulation.py

2bdccd8

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

Update SimPEG/simulation.py

8439c7f

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

Update SimPEG/simulation.py

5e1d43a

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

Update SimPEG/simulation.py

12694da

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

Update SimPEG/simulation.py

b45abb3

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

Replace UncertaintyArray for numpy.ndarray in docstrings

d8dd641

Co-authored-by: Lindsey Heagy <lindseyheagy@gmail.com>

santisoler reviewed Apr 2, 2024

View reviewed changes

SimPEG/simulation.py Outdated Show resolved Hide resolved

santisoler added 2 commits April 2, 2024 09:16

Capitalize first letter of string

54cad2e

Merge branch 'main' into Doc_BaseSimulations

b6e18c9

santisoler reviewed Apr 2, 2024

View reviewed changes

SimPEG/data.py Outdated Show resolved Hide resolved

santisoler reviewed Apr 2, 2024

View reviewed changes

SimPEG/data.py Outdated Show resolved Hide resolved

Replace UncertaintyArrays for np.ndarray in docstrings

c762ce9

santisoler changed the title ~~Doc base simulations~~ Improve documentation for base simulation classes Apr 2, 2024

santisoler merged commit eeb406f into simpeg:main Apr 2, 2024
16 checks passed

ghwilliams deleted the Doc_BaseSimulations branch May 16, 2024 14:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documentation for base simulation classes #1295

Improve documentation for base simulation classes #1295

ghwilliams commented Oct 16, 2023 •

edited by santisoler

codecov bot commented Nov 28, 2023 •

edited

santisoler left a comment

ghwilliams commented Jan 15, 2024

santisoler left a comment •

edited

lheagy left a comment

santisoler commented Apr 2, 2024

Improve documentation for base simulation classes #1295

Improve documentation for base simulation classes #1295

Conversation

ghwilliams commented Oct 16, 2023 • edited by santisoler

Summary

PR Checklist

Reference issue

What does this implement/fix?

Additional information

codecov bot commented Nov 28, 2023 • edited

Codecov Report

santisoler left a comment

Choose a reason for hiding this comment

ghwilliams commented Jan 15, 2024

santisoler left a comment • edited

Choose a reason for hiding this comment

lheagy left a comment

Choose a reason for hiding this comment

santisoler commented Apr 2, 2024

ghwilliams commented Oct 16, 2023 •

edited by santisoler

codecov bot commented Nov 28, 2023 •

edited

santisoler left a comment •

edited