InterfaceMarkup

The interface to any new or modified routine in fparser must be fully documented using Sphinx mark-up. An example of how to do this is shown below:

def parse(alg_filename, api="", invoke_name="invoke", inf_name="inf",
          kernel_path="", line_length=False):
    '''
    Takes a GungHo algorithm specification as input and outputs an AST of
    this specification and an object containing information about the
    invocation calls in the algorithm specification and any associated kernel
    implementations.

    :param str alg_filename: The file containing the algorithm specification.
    :param str invoke_name: The expected name of the invocation calls in the\
                            algorithm specification
    :param str inf_name: The expected module name of any required\
                         infrastructure routines.
    :param str kernel_path: The path to search for kernel source files (if\
                            different from the location of the algorithm\
                            source).
    :param line_length: A logical flag specifying whether we\
                        care about line lengths being longer ...
    :type line_length: bool
    :return: A 2-tuple containing the top-level node in the AST and an object\
             describing all of the invoke()'s found in the Algorithm file
    :rtype: :py:class:`psyclone.psyGen.SubroutineGen`, :py:class:`psyclone.parser.Invokes`

    :raises IOError: If the filename or search path does not exist.
    :raises ParseError: If there is an error in the parsing.
    :raises RuntimeError: If there is an error in the parsing.

    '''

Note that each different exception that the routine can raise is documented separately. If an argument type is a Python built-in (e.g. str, int or bool) then the type can be specified in-line with the argument description. However, if it is of a derived type then, for clarity, it should be specified in a separate :type my_arg: line.