Closed jakubjezek001 closed 1 month ago
here is great example of the docsting style, taken from here https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example:
"""
.. module:: useful_1
:platform: Unix, Windows
:synopsis: A useful module indeed.
.. moduleauthor:: Andrew Carter <andrew@invalid.com>
"""
def public_fn_with_googley_docstring(name, state=None):
"""This function does something.
Args:
name (str): The name to use.
Kwargs:
state (bool): Current state to be in.
Returns:
int. The return code::
0 -- Success!
1 -- No good.
2 -- Try again.
Raises:
AttributeError, KeyError
A really great idea. A way you might use me is
>>> print public_fn_with_googley_docstring(name='foo', state=None)
0
BTW, this always returns 0. **NEVER** use with :class:`MyPublicClass`.
"""
return 0
def public_fn_with_sphinxy_docstring(name, state=None):
"""This function does something.
:param name: The name to use.
:type name: str.
:param state: Current state to be in.
:type state: bool.
:returns: int -- the return code.
:raises: AttributeError, KeyError
"""
return 0
def public_fn_without_docstring():
return True
def _private_fn_with_docstring(foo, bar='baz', foobarbas=None):
"""I have a docstring, but won't be imported if you just use ``:members:``.
"""
return None
class MyPublicClass(object):
"""We use this as a public class example class.
You never call this class before calling :func:`public_fn_with_sphinxy_docstring`.
.. note::
An example of intersphinx is this: you **cannot** use :mod:`pickle` on this class.
"""
def __init__(self, foo, bar='baz'):
"""A really simple class.
Args:
foo (str): We all know what foo does.
Kwargs:
bar (str): Really, same as foo.
"""
self._foo = foo
self._bar = bar
def get_foobar(self, foo, bar=True):
"""This gets the foobar
This really should have a full function definition, but I am too lazy.
>>> print get_foobar(10, 20)
30
>>> print get_foobar('a', 'b')
ab
Isn't that what you want?
"""
return foo + bar
def _get_baz(self, baz=None):
"""A private function to get baz.
This really should have a full function definition, but I am too lazy.
"""
return baz
looking at the example, should we remove the type hints from signatures or rather add more?
looking at the example, should we remove the type hints from signatures or rather add more?
definitelly rather more please :)
your wish is my command :D
i'll start with this when #8 got merged as it brings quite some changes. i'll probably do that directly on #17 as i already added some vanilla sphinx autodocs
Description:
In order to enhance our code API, it is essential that we refine the docstrings for every method and class. Additionally, each module category's
__init__.py
file should contain a clear and concise docstring explaining its purpose. This initiative will be particularly beneficial as we transition to using Sphinx for documentation generation.Steps to Reproduce:
__init__.py
file includes a descriptive docstring.Expected Outcome:
Improved code readability and documentation quality, facilitating better understanding and usage of the API.