Skip to content

Doc: add Attributes section#700

Merged
mrava87 merged 17 commits into
PyLops:devfrom
mrava87:doc-attributes
Oct 22, 2025
Merged

Doc: add Attributes section#700
mrava87 merged 17 commits into
PyLops:devfrom
mrava87:doc-attributes

Conversation

@mrava87
Copy link
Copy Markdown
Collaborator

@mrava87 mrava87 commented Oct 8, 2025

Closes #488.

This PR aims to update all Attributes sections of the docstrings of operators and solvers, including all of the internal attributes that we want users/devs to be aware of (previously we simply reported shape/explicit and missed many useful ones) - note that Parameters that are saved as class members are not added to the Attributes list, only new class members are.

Moreover, since the Attributes sections are now meaningful we make them appear in the Sphinx documentation.

Additional:

  • some of the attributes that I feel should be kept hidden from users (to prevent anyone from tinkering with them) are now private (ie added _*). Ideally I would have like to be more aggressive but I was worried about breaking backward compatibility for some attributes that users may print or check so I decided to be very conservative.
  • all np.ndarray in docstrings have been switched to numpy.ndarray to be able to have hyperlinks pointing to the NumPy documentation.
  • all :obj:func in the documentation are turned into :obj:callable
  • fixed all outstanding warnings in the Sphinx documentation build

@mrava87 mrava87 added enhancement New feature or request Core Pulls for core PyLops library labels Oct 18, 2025
@mrava87 mrava87 marked this pull request as ready for review October 18, 2025 21:32
@mrava87 mrava87 requested a review from cako October 18, 2025 21:32
@mrava87
Copy link
Copy Markdown
Collaborator Author

mrava87 commented Oct 18, 2025

@cako this was long overdue and with some help with Copilot it took less than expected (I run out of the autocompletion allowance this months ahah).

I am not expecting you to look at this line by line, but let me know if you have any general suggestion 😄

Copy link
Copy Markdown
Collaborator

@cako cako left a comment

Choose a reason for hiding this comment

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

This is amazing!! Huge effort but will result in much better docs!! Thanks

@mrava87 mrava87 merged commit 3eba33a into PyLops:dev Oct 22, 2025
20 checks passed
@mrava87 mrava87 deleted the doc-attributes branch October 22, 2025 07:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Core Pulls for core PyLops library enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Attributes field in docstrings of operators

2 participants