Skip to content

Changes

Page history
florent.jaillet created page: home authored by Florent Jaillet's avatar Florent Jaillet
Hide whitespace changes
Inline Side-by-side
home.md 0 → 100644
View page @ a6334af0
How to document the code in ltfatpy
=================================
This page is intended for the ltfatpy developers and describes the convention used to document the code of ltfatpy.
Syntax
---------
The ltfatpy documentation is generated using [sphinx](http://sphinx-doc.org), so all the docstrings must be written using the syntax recognized by sphinx, which is documented [here](http://sphinx-doc.org/rest.html#rst-primer) and [here](http://sphinx-doc.org/markup/index.html#sphinxmarkup).
Documenting modules
----------------------------
At the beginning of each module (so at the beginning of each file), add a short docstring describing the content of the module, and add the module author(s) name(s) without any e-mail address (a main e-mail address for contact is given in the main page of the documentation).
Add a line identifying the octave file name and the version of ltfat used for porting the file.
Example:
```python
""" Module of frequency index of FFT modulations computation
Ported from ltfat_2.1.0/fourier/fftindex.m
.. moduleauthor:: Florent Jaillet
"""
```
Documenting functions
---------------------
Each function should have a docstring documenting its use and behaviour.
As much as possible, document the content of the inputs and outputs of the
functions, including their data types.
### Usage
For this, you can keep and adapt the "usage" section found in the ltfat octave function. Use `|` before each usage line like this:
```
- Usage:
| ``(c, Ls, g) = dgt(f, g, a, M)``
| ``(c, Ls, g) = dgt(f, g, a, M, L)``
| ``(c, Ls, g) = dgt(f, g, a, M, L, pt)``
```
### Input parameters
To document the inputs, use the fields `param` and `type` to describe each input.
When the data type is a single word, use the following compact syntax:
```
:param int a: Length of time shift
```
When the type is more complex, use the type field like this:
```
:param g: Window function
:type g: str, dict or numpy.ndarray of float64 or complex128
```
To specify the type of numpy arrays use the following syntax (specifying the dtype and number of dimensions is optional):
```
numpy.ndarray of float64 with ndim=3
```
### Output parameters
To document the outputs, use the `returns`, `rtype`, `var`, `vartype` fields.
If the function returns a single value, there is no need to name the output and you can use only `returns` and `rtype`.
If the function returns multiple values, use the following type of syntax:
```
- Output parameters:
:returns: ``(g, info)``
:rtype: tuple
:var numpy.ndarray g: the computed window
:var dict info: the information dictionary
```
### Exceptions
If needed, you can also document the exception raised by the function using the `raises` field.
### Indentation
Note that all the fields `param`, `type`, `returns`, `rtype`, `var`, `vartype` and `raises` must be indented at the same level than the opening of the docstring to be interpreted as they should by sphinx. That is to say that the following works:
```python
def lcm(X, Y):
"""Compute the least common multiple
- Inputs:
:param int X: The first of the two integers for which to compute the
least common multiple
:param int Y: The second of the two integers for which to compute the
least common multiple
- Outputs:
:returns: the least common multiple of **X** and **Y**
:rtype: int
"""
if not isinstance(X, int) or not isinstance(Y, int):
raise TypeError('X and Y must be int.')
return X * Y // gcd(X, Y)
```
while the following doesn't work:
```python
def lcm(X, Y):
"""Compute the least common multiple
- Inputs:
:param int X: The first of the two integers for which to compute the
least common multiple
:param int Y: The second of the two integers for which to compute the
least common multiple
- Outputs:
:returns: the least common multiple of **X** and **Y**
:rtype: int
"""
if not isinstance(X, int) or not isinstance(Y, int):
raise TypeError('X and Y must be int.')
return X * Y // gcd(X, Y)
```
### Functions, parameters and code highlighting
In the docstrings, use the references to functions when needed, highlight the input parameters in bold, and highlight any code or value using literal, as in this example where `order` is a parameter:
```
``assert_groworder`` is meant to be used in conjunction with
:func:`~ltfatpy.comp.assert_sigreshape_pre.assert_sigreshape_pre` and
:func:`~ltfatpy.comp.assert_sigreshape_post.assert_sigreshape_post`. It is
used to modify the **order** parameter in between calls in order to expand
the processed dimension by ``1``, i.e. for use in a routine that creates 2D
output from 1D input, for instance in :func:`~ltfatpy.gabor.dgt.dgt` or
:func:`filterbank`.
```
### See also
To add a "See also" section in a docstring, use the following syntax:
```
.. seealso:: :func:`~ltfatpy.gabor.dgt.dgt`,
:func:`~ltfatpy.gabor.tfplot.tfplot`,
:func:`~ltfatpy.gabor.sgram.sgram`,
:func:`~ltfatpy.gabor.plotdgtreal.plotdgtreal`
```
### Notes
To add a "Note" section in a docstring, use the following syntax:
```
.. note::
If soft- or Wiener thresholding is selected, only ``N-1``
coefficients will actually be returned. This is caused by the Nth
coefficient being set to zero.
```
### References and bibliography
The bibliography is handled using [sphinxcontrib-bibtex](https://pypi.python.org/pypi/sphinxcontrib-bibtex).
To add a reference in a docstring, use the following syntax, where the references identifiers are the one used in the bibtex file:
```
- References:
:cite:`fest98,gr01`
```