forked from pearu/f2py
-
Notifications
You must be signed in to change notification settings - Fork 30
InterfaceMarkup
Rupert Ford edited this page Mar 7, 2020
·
2 revisions
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: 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:
- 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. - the separation of input arguments, return values and exceptions.
- the blank line before the end quotes.
- the "" when there are multiple lines and the indentation of text on subsequent lines. The example shows an indentation of 4 but indentation to the start of the text on the previous line is also acceptable.
- that description text starts with a lower case word and finishes with a full stop.