InterfaceMarkup

The interface to any new or modified routine in PSyclone 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.

    Code examples that are able to be checked using doctest can be added
    like this:

    .. doctest::
       >>> from psyclone.domain.nemo.transformations import \\
       ...     NemoAllArrayAccess2LoopTrans
       >>> from psyclone.psyir.backend.fortran import FortranWriter
       >>> from psyclone.psyir.frontend.fortran import FortranReader
       >>> from psyclone.psyir.nodes import Assignment
       >>> code = ("program example\\n"
       ...         "  real a(10,10), b(10,10)\\n"
       ...         "  integer :: n\\n"
       ...         "  a(1,n-1) = b(1,n-1)\\n"
       ...         "end program example\\n")
       >>> psyir = FortranReader().psyir_from_source(code)
       >>> assignment = psyir.walk(Assignment)[0]
       >>> NemoAllArrayAccess2LoopTrans().apply(assignment)
       >>> print(FortranWriter()(psyir))
       program example
         real, dimension(10,10) :: a
         real, dimension(10,10) :: b
         integer :: n
         integer :: ji
         integer :: jj
       <BLANKLINE>
         do ji = 1, 1, 1
           do jj = n - 1, n - 1, 1
             a(ji,jj) = b(ji,jj)
           enddo
         enddo
       <BLANKLINE>
       end program example
       <BLANKLINE>

    :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.

    '''

Some important details:

1. Each section (description, parameter, return value, exceptions) must be separated by an empty line. Between the entries in one section there must not be an empty line.
2. Sentences describing the function, a parameter, return value or exception should start with a capital letter, and end with a full stop. Be aware that even though the :return(s):: section might read like one sentence (:return: the sum of all elements), when the description is convert to HTML, the return and description are on different lines, and as such the description of the return value should be written as a stand-alone sentence.
3. If a parameter description, type, return value or exception is continued to the next line, then each continued line must be aligned consistently. For long lines this is typically an additional four spaces of indent or, for short lines, they may be aligned with the start of the description on the first line. Examples of both are shown above.
4. 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.
5. If Python type-hinting is used in the definition of the class/method then the type information should be omitted from the docstring.
6. The type of a parameter or return value should be set in lower case letters, with no punctuation characters at the end. In HTML the type is set in parenthesis after the name of the parameter, which would include punctuation characters: parent (psyclone.f2pygen.SubroutineGen.) – the parent...
7. The closing ''' of the interface description can be at the end of a text line if the overall description is short. Otherwise it should be on a separate line, and there should be an empty line before the '''.
8. When an argument can be one of a number of subclasses of a parent class then the argument should be specified as "subclass of ". For example :rtype: subclass of :py:class:'psyclone.psyir.nodes.Node'
9. If the routine can raise many (>~3) exceptions of the same type then, rather than list them all separately, they may be summarised, e.g. :raises TypeError: if any of the supplied arguments are of the wrong type..
10. If runnable code examples are provided then they should run successfully using doctest python -m doctest -c file.rst
11. .. doctest:: is required if the output contains indentation as otherwise sphinx complains.
12. Python code should be preceded by >>> and continuation lines by ...
13. Any blank lines in the output should be replaced with <BLANKLINE>