2.1. Documentation Notation and Formatting

In addition to text with references to variables, functions, file names, etc., this documentation contains many descriptions of function inputs and outputs. This is a semi-standard Python way of describing the user interface to a function.

This documentation is built by the Sphinx documentation software, which has certain features that may not be obvious to all users of pyCart and the other parts of the CAPE package. The docstrings like the one shown above are read by Sphinx and turned into formatted text such as cape.pycart.inputCntl.InputCntl.SetAlpha(). The basic layout of these docstrings, with optional portions in parentheses, is as follows.

Short description of the function or class

(More detailed description if necessary)

:Call:
    >>> Example Python call showing how to use the function
    (>>> Alternate examples if function can be used multiple ways)
:Inputs:
    *Name_input1*: :class:`variable_type`
        Description of first input
    *Name_input2*: :class:`variable_type`
        Description of second input
:Outputs:
    *Name_output1*: :class:`variable_type`
        Description of first output
    *Name_output2*: :class:`variable_type`
        Description of second output
:Versions:
    * Date ``@Author``: Short description

Sphinx automatically turns this text into the following format.

Short description of the function or class

(More detailed description if necessary)

Call:

>>> Example Python call showing how to use the function
(>>> Alternate examples if function can be used multiple ways)

Inputs:

Name_input1: variable_type

Description of first input

Name_input2: variable_type

Description of second input

Outputs:

Name_output1: variable_type

Description of first output

Name_output2: variable_type

Description of second output

Versions:

• Date @Author: Short description

This documentation uses much of the same syntax and markup throughout the rest of the document, and this quick guide may become useful in cases of confusion or ambiguity.

2.1.1. Documentation Syntax Guide

Understanding this syntax can be somewhat helpful for reading the documentation strings, and it provides a useful shorthand when discussing features of the code. A table of how various syntaxes are used is below.

Syntax	Formatted	Description/Purpose
``f(a)``	f(a)	Raw text or source code
``$PYCART``	$PYCART	Environment variable
*a*	a	Variable name
*a>b*	a>b	Key b of a, a["b"]
:Inputs:	Inputs:	Dictionary-style header
:file:`pyCart.json`	pyCart.json	File name
:mod:`cape.tri`	cape.tri	Module name
:class:`int`	int	Class or type of variable
:func:`SetAlpha`	SetAlpha()	Function name

The class, mod, and func keys generate links to their formatted documentation when Sphinx can find it.

Some inputs and outputs can have multiple allowed types, which is also represented in the docstrings. In addition, lists, dictionaries, and NumPy arrays often have a type, which is shown in parentheses. For example, [0.1, 0.2, 0.34] might be listed as list[float], and {"name": "a", "place": "b"} might be listed as dict[str]. Finally, default values are sometimes placed in curly braces. An example portion of a document string is shown below.

:Inputs:
    *a*: :class:`list`\ [:class:`float`]
        Description of a list of float values
    *b*: :class:`int` | ``None``
        Description of variable that is either an integer or nothing
    *c*: :class:`dict` | :class:`list`
        Description of multiple ways to represent some data
    *q*: {``True``} | ``False``
        Description of Boolean variable that defaults to ``True``

The formatted version of the above looks like this.

Inputs:

a: list[float]

Description of a list of float values

b: int | None

Description of variable that is either an integer or nothing

c: dict | list

Description of multiple ways to represent some data

q: {True} | False

Description of Boolean variable that defaults to True

2.1.2. Keyword Arguments

One aspect of possible confusion to new or novice Python users is the so-called keyword arguments. For example, in the following example command, there are regular arguments and keyword arguments.

comp = 'CA'
ylbl = 'CA (Axial force coefficient)'
FM.PlotCoeff(comp, YLabel=ylbl)

In this case comp is a regular input, often called an “argument” in Python jargon. Then YLabel is a keyword input or keyword argument, which is specified with an equal sign in the function call. The advantage of keyword arguments is that they can be given in any order, and many of them can be skipped when default values should be used. For example, the following two commands are identical.

FM.PlotCoeff('CA', XLabel='i', YLabel='CA')
FM.PlotCoeff('CA', YLabel='CA', XLabel='i')

Another tool for using keywords is that a dict can be used as a list of keywords inputs. The following two commands are identical.

kw = {"d": 0.1, "k": 3.0, "YLabel": "Cx"}
FM.PlotCoeff('CA', **kw)
FM.PlotCoeff('CA', d=0.1, k=3.0, YLabel="Cx")