diff --git a/docs/source/docstrings.rst b/docs/source/docstrings.rst index b584270..e45339d 100644 --- a/docs/source/docstrings.rst +++ b/docs/source/docstrings.rst @@ -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 `_) and ``NumPy`` (see `here `_), 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 `_) and ``NumPy`` (see `here `_), 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 @@ -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 `_. +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 `_. 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. @@ -171,6 +171,6 @@ Docstrings in VS code If you are using VS code, the `Python Docstring `_ 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.