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

docstrings in python version / Python documentation #1328

Open
PrometheusPi opened this issue Nov 11, 2022 · 4 comments
Open

docstrings in python version / Python documentation #1328

PrometheusPi opened this issue Nov 11, 2022 · 4 comments

Comments

@PrometheusPi
Copy link
Member

Is your feature request related to a problem? If so, please describe.
If one interactively uses openpmd-api in python e.g. via ipython or jupyter, one might need to look up the usage via reading the docstrings as e.g. below

Python:

import openpmd_api as io
io.Series?

results in a less-user-friendly output

Docstring:      <no docstring>
Init docstring:
__init__(*args, **kwargs)
Overloaded function.

1. __init__(self: openpmd_api.openpmd_api_cxx.Series, filepath: str, access: openpmd_api.openpmd_api_cxx.Access, options: str = '{}') -> None

2. __init__(self: openpmd_api.openpmd_api_cxx.Series, filepath: str, access: openpmd_api.openpmd_api_cxx.Access, mpi_communicator: object, options: str = '{}') -> None
File:           /trinity/shared/pkg/filelib/openpmd/0.14.4/gcc/7.3.0/openmpi/4.1.1-no-cuda/lib64/python3.6/site-packages/openpmd_api/openpmd_api_cxx.cpython-36m-x86_64-linux-gnu.so
Type:           pybind11_type
Subclasses:     

Describe the solution you'd like
It would be fantastic if one could have a more readably docstring for the openPMD-api python module.

Describe alternatives you've considered
Currently the best way (for me) is to follow the examples.

Additional context
This is not urgent, but it would enhance productivity if one does not have to look for the right example or to scroll through the source code to figure out how to use the python version.

@ax3l
Copy link
Member

ax3l commented Nov 15, 2022

That's a great point and was a bit undervalued for the initial binding implementation.

One can add to a pybind binding multiple optional arguments with a raw string (body) and py::arg("name") for positional function parameters, including an = ... assignment for their default values.

Here is an example in ImpactX:
https://github.com/ECP-WarpX/impactx/blob/22.11/src/python/elements.cpp#L136-L146

PRs that improve binding doc strings very welcome! :)

@PrometheusPi
Copy link
Member Author

Thanks @ax3l for your reply. And thanks for your code example. I will see if/when I hae time.

@franzpoeschel
Copy link
Contributor

Might be helpful for a start: https://github.com/pybind/pybind11_mkdoc

@PrometheusPi
Copy link
Member Author

Thanks @franzpoeschel

@franzpoeschel franzpoeschel changed the title docstrings in python version docstrings in python version / Python documentation Jun 22, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants