Writing documentation

Writing docstrings

All functions are required to have a header placed under the function definition that is based on the google docstring style. The header should be enough for someone who has never seen the function before to be able to use it and understand the outputs.

Examples: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

Template

'''
Broad description of what the function does.

Example:
    Example of how to use the function.
    Include any images / equations, etc. that would help explain how to use the function.
    
Args:
    varIn_name1 (dim label1, dim label2): Description
    varIn_name2 (data type): Description
        
Returns:
    type: description
'''

Example

locate_trials_with_event(trial_events, event_codes, event_columnidx=None):
    '''
    Given an array of trial separated events, this function goes through and finds the event sequences corresponding to the trials
    that include a given event. If an array of event codes are input, the function will find the trials corresponding to
    each event code. 
    
    Args:
        trial_events (ntr, nevents): Array of trial separated event codes
        event_codes (int, str, list, or 1D array): Event code(s) to find trials for. Can be a list of strings or ints
        event_column (int): Column index to look for events in. Indexing starts at 0. Keep as 'None' if all columns should be analyzed.
        
    Returns:
        tuple: Tuple containing:
            | **list of arrays:** List where each index includes an array of trials containing the event_code corresponding to that index. 
            | **1D Array:** Concatenated indices for which trials correspond to which event code.
                        Can be used as indices to order 'trial_events' by the 'event_codes' input.
    Example::
        >>> aligned_events_str = np.array([['Go', 'Target 1', 'Target 1'],
                ['Go', 'Target 2', 'Target 2'],
                ['Go', 'Target 4', 'Target 1'],
                ['Go', 'Target 1', 'Target 2'],
                ['Go', 'Target 2', 'Target 1'],
                ['Go', 'Target 3', 'Target 1']])
        >>> split_events, split_events_combined = locate_trials_with_event(aligned_events_str, ['Target 1','Target 2'])
        >>> print(split_events)
        [array([0, 2, 3, 4, 5], dtype=int64), array([1, 3, 4], dtype=int64)]
        >>> print(split_events_combined)
        [0 2 3 4 5 1 3 4]   
    '''   

Tips for vscode

Use the reStructuredText extension to view a preview of .rst files

You can also use the Python Docstring Generator extension to automatically generate docstrings for your functions.

Adding images

In your docstring or in the .rst file of your choice include the line

.. image:: _images/your-image.png

Then put your image into /docs/source/_images/

Adding equations

You can include any LaTeX equations in the documentation.

In your docstring include:

.. math:: \\frac{ \\sum_{t=0}^{N}f(t,k) }{N}

Notice the double backslash \\ to delimit the escape character in python.

To add math to an .rst file of your choice:

.. math:: 

    \frac{ \sum_{t=0}^{N}f(t,k) }{N}