

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://sphinxdoc.org), so all the docstrings must be written using the syntax recognized by sphinx, which is documented [here](http://sphinxdoc.org/rest.html#rstprimer) and [here](http://sphinxdoc.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 email address (a main email 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 ``N1``



coefficients will actually be returned. This is caused by the Nth



coefficient being set to zero.



```






### References and bibliography






The bibliography is handled using [sphinxcontribbibtex](https://pypi.python.org/pypi/sphinxcontribbibtex).






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`



``` 