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.

Sign up for GitHub

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

Jump to bottom

A standard docstring format for PySCeS #99

Open

bgoli opened this issue May 8, 2024 · 0 comments

Member

bgoli commented May 8, 2024 •

edited

I've been playing around with using LLM's to generate/convert docstrings and found two docstring formats for Python that are widely used:

PEP 287 (https://peps.python.org/pep-0287/) reST and Sphinx compatible but slightly boring
Numpydoc (https://numpydoc.readthedocs.io/en/latest/format.html) reST and Sphinx compatible (with plugin) and slightly more sophisticated when it comes to dealing with code examples

I'm considering both to see if there are any quality differences in the AI output but perhaps we should, in general, select one for PySCeS?

Update. It looks like Numpydoc format gives more consistently formatted output so that would be my suggestion to use for new docstrings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment