.. _docstring_conventions: Docstring Conventions ===================== For the documentation we follow the `Numpy docstring conventions `_. Example docstrings are given below. .. contents:: Table of contents :local: :backlinks: none Docstring Content ----------------- - You may write **doctests** in the **Examples** section to give more detail about a function - **Subclasses** do **not** document methods/attributes from superclass that are not overwritten - Functionality relevant to users that is added to a class with magic methods like an extended ``==``, the ``in`` keyword etc. is documented in the ``Notes`` section of the class docstring **Attributes** of a class, that are also **Parameters**, are not documented in a redundant way. **DO** .. code-block:: python """ Parameters ---------- fct : function Function defining the net. parameters : dict (default=tuple(())) Parameters of `fct`. Attributes ---------- fct parameters : ddg.parameters.Parameters """ **DON'T** .. code-block:: python """ Parameters ---------- fct : function Function defining the net. parameters : dict (default=tuple(())) Parameters of `fct`. Attributes ---------- fct : function Function defining the net. parameters : ddg.parameters.Parameters Parameters of `fct`. """ Naming & Reference ------------------ - **Numpy arrays** are referred to by "``numpy.ndarray of shape (n,m)``" - **Keyword arguments** are marked as such by stating the **default** value the folowing way: "``param : bool (default=True)``" Mathematical Equations ---------------------- - In the **notes section** or in the **description body** of the docstring (the paragraph), mathematical equations can be written in **ascii art** or in **pseudocode**, so that it is readable in the docstring - for **ascii art** to display correctly, add ``::`` before the ascii art paragraph, or put back ticks ````` around inline equations, as in: .. code-block:: python def fourth_point_from_cross_ratio(z, z1, z2, q): """ Get `z12` such that `cr(z, z1, z12, z2) = q` For a quadrilateral of the form :: z2 ----- z12 | | | | | | z ----- z1 with given `z,z1,z2` and `q`, compute `z12` .""" - using back ticks also prevents sphinx from interpreting part of your equation as markdown delimiters such as `*` and `_` - you can use the software `sage `_ for ascii art. - If you want to explain a LOT of math, you can put it into the user's guide section for mathematical background. As explained in the `users guide conventions `_, there math should be written in **latex**. Example: Function Docstring ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python def func(arg1, arg2): """A short (up to 50 characters) summary that does not use variable names or the function name. [Extended description of function, used to clarify functionality, not to discuss implementation details or background theory, which should rather be done in a Notes section.] Parameters ---------- arg1 : int Description of `arg1` and possible default value arg2 : iterable object Description of `arg2` Returns ------- bool Description of return value Raises ------ ValueError Description of what raises an exception of the above type Warns ----- UserWarning Description of what raises a warning of this type, similar to the "Raises" section Warnings -------- Things the user should be aware of! Rendered as a red warning box. Notes ----- Optional section that provides additional information about the code, further details about the algorithm and implementation. """ return True Layout ~~~~~~ - To keep indention and line breaks, you **may** use vertical lines in front of the docstring: .. code-block:: python """ create_spheres : bool | If true, spheres will be created around the vertices of the resulting | Delaunay surface. | light blue: original vertices | white: vertices introduced for visualization, | Default: True """ Example: Class Docstring ------------------------ .. code-block:: python class Net(Transformable, Callable, Updatable, UpdateTrigger): """Base class for nets. Parameters ---------- fct : function Function defining the net. domain : ddg.nets.Domain or list of intervals Domain of `fct`. name : str (default='Net') Name of the net (mostly used for blender conversion). Attributes ---------- fct : function Function defining the net. domain : ddg.nets.Domain Domain of `fct`. parameters : ddg.nets.Parameters Parameters of `fct`. name : str Name of the net (mostly used for blender conversion). changed : bool This argument is set `True` when the parameters of the net are not in their original state. dimension : int Dimension of the domain. Notes ----- Instances of this class are callable. Calling a net will return the output of `fct` transformed with any transformations that were applied using `transform`. See Also -------- SmoothNet, DiscreteNet, NetCollection """ Quirks with the Methods section ------------------------------- The ``Methods`` section in the docstring is considered optional. It also works differently than the other sections in the generated html documentation: It will generate a table instead of a list in the style of e.g. the ``Parameters`` section: .. image:: auto_methods.png :width: 500px :align: center The short description comes from the first line of the docstring of the method. You can also write your own descriptions if the method doesn't have its own docstring. If it does, these will simply be ignored in the generated documentation, but they might still be useful for people reading the code. .. code-block:: python """ Methods ------- another_method This is another method the_second_one This is the second method """ produces .. image:: manual_methods.png :width: 500px :align: center **Never** mix the two styles because it will look terrible: .. image:: mixed_methods.png :width: 500px :align: center This means that either all or none of the listed methods must have their own docstrings.