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

Update docstrings.rst #6

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/source/docstrings.rst
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
Writing docstrings
==================

There are several different docstring formats which one can use in order to enable Sphinx's ``autodoc`` extension to automatically generate documentation. For this tutorial we will use the ``Sphinx`` format, since, as the name suggests, it is the standar format used with Sphinx. Other formats include ``Google`` (see `here <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`_) and ``NumPy`` (see `here <http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy>`_), but they require the use of Sphinx's ``napoleon`` extension, which is beyond the scope of this tutorial.
There are several different docstring formats which one can use in order to enable Sphinx's ``autodoc`` extension to automatically generate documentation. For this tutorial we will use the ``Sphinx`` format, since, as the name suggests, it is the standard format used with Sphinx. Other formats include ``Google`` (see `here <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`_) and ``NumPy`` (see `here <http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy>`_), but they require the use of Sphinx's ``napoleon`` extension, which is beyond the scope of this tutorial.

The Sphinx docstring format
***************************

In general, a typical ``Sphinx`` docsting has the following format:
In general, a typical ``Sphinx`` docstring has the following format:

.. code-block:: python

Expand All @@ -21,7 +21,7 @@ In general, a typical ``Sphinx`` docsting has the following format:
:rtype: [ReturnType]
"""

A pair of ``:param:`` and ``:type:`` directive options must be used for each parameter we wish to document. The ``:raises:`` option is used to describe any errors that are raised by the code, while the ``:return:`` and ``:rtype:`` options are used to describe any values returned by our code. A more thorough explanation of the ``Sphinx`` docsting format can be found `here <https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html>`_.
A pair of ``:param:`` and ``:type:`` directive options must be used for each parameter we wish to document. The ``:raises:`` option is used to describe any errors that are raised by the code, while the ``:return:`` and ``:rtype:`` options are used to describe any values returned by our code. A more thorough explanation of the ``Sphinx`` docstring format can be found `here <https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html>`_.

Note that the ``...`` notation has been used above to indicate repetition and should not be used when generating actual docstrings, as can be seen by the example presented below.

Expand Down Expand Up @@ -171,6 +171,6 @@ Docstrings in VS code

If you are using VS code, the `Python Docstring <https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring>`_ extension can be used to auto-generate a docstring snippet once a function/class has been written. If you want the extension to generate docstrings in ``Sphinx`` format, you must set the ``"autoDocstring.docstringFormat": "sphinx"`` setting, under File > Preferences > Settings.

Note that it is best to write the docstrings once you have fully defined the function/class, as then the extension will generate the full dosctring. If you make any changes to the code once a docstring is generated, you will have to manually go and update the affected docstrings.
Note that it is best to write the docstrings once you have fully defined the function/class, as then the extension will generate the full docstring. If you make any changes to the code once a docstring is generated, you will have to manually go and update the affected docstrings.