1Documentation standards for petsc4py 2==================================== 3 4Subject to exceptions given below, new contributions to petsc4py **must** 5include `type annotations <python:typing>` for function parameters and results, 6and docstrings on every class, function and method. 7 8The documentation should be consistent with the corresponding C API 9documentation, including copying text where this is appropriate. More in-depth 10documentation from the C API (such as extended discussions of algorithmic or 11performance factors) should not be copied. 12 13Docstring standards 14------------------- 15Docstrings are to be written in `numpydoc:format` format. 16 17The first line of a class, function or method docstring must be a short 18description of the method in imperative mood ("Return the norm of the matrix.") 19"Return" is to be preferred over "Get" in this sentence. A blank line must 20follow this description. Use one-liner descriptions for properties. 21 22If the corresponding C API documentation of a method lists a function as being 23collective, then this information must be repeated on the next line of the 24docstring. Valid strings are: "Not collective.", "Logically collective.", 25"Collective.", "Neighborwise collective.", or "Collective the first time it is 26called". 27 28The initial description section can contain more information if this is useful. 29In particular, if there is a PETSc manual chapter about a class, then this 30should be referred to from here. 31 32Use double backticks around literals (like strings and numbers), e.g., 33\`\`2\`\`, \`\`"foo"\`\`. 34 35Reference PETSc functions simply using backticks, e.g., `petsc.KSP` refers to 36the PETSc C documentation for KSP. Do **not** use URLs in docstrings. Always 37use Intersphinx references. 38 39The following sections describe the use of numpydoc sections. Other sections 40allowed by numpydoc may be included if they are useful. 41 42Parameters 43.......... 44 45This is required for methods unless there are no parameters, or it will be 46completely obvious to even a novice user what the parameters do. 47 48If a class has a non-trivial constructor, the arguments of the constructor and 49their types must be explicitly documented within this section. 50 51For methods, types should only be specified in this section if for some reason 52the types provided by typing prove to be inadequate. If no type is being 53specified, do not include a colon (``:``) to the right of the parameter name. 54 55Use `Sys.getDefaultComm` when specifying the default communicator. 56 57Returns 58....... 59 60This should only be specified if the return value is not obvious from the 61initial description and typing. 62 63If a "Returns" section is required, the type of the returned items *must* be 64specified, even if this duplicates typing information. 65 66See Also 67........ 68 69If any of the following apply, then this section is required. The order of 70entries is as follows. Other links are permitted in this section if they add 71information useful to users. 72 73Every ``setFromOptions`` must include the link ``petsc_options``. 74 75Any closely related part of the petsc4py API not already linked in the 76docstring should appear (e.g. setters and getters should cross-refer). 77 78If there is a corresponding C API documentation page, this must be linked from 79the "See also" section, e.g. ``petsc.MatSetValues``. 80 81End docstring with an empty line - "closing three quotation marks must be on a 82line by itself, preferably preceded by a blank line" 83 84Type hint standards 85------------------- 86 87If returning ``self``, use ``-> Self`` in function signature. 88 89Type hints are not required when the static type signature includes a PETSc 90type (e.g. ``Vec x``). These will be automatically generated. This will also 91work for ``= None``. When using type hints, use spacing around the equals in 92any ``= None``. 93 94Communicators in type signatures must use Python typing instead of c-typing 95(i.e. ``comm: Comm`` not ``Comm comm``). This is because communicators 96can come from ``mpi4py`` and not just the ``petsc4py.PETSc.Comm`` class. 97 98For petsc4py native types that are strings, the type is ``argument: 99KSP.Type | str`` (not e.g.: ``KSPType argument``). If the type is strictly an 100enum the ``| str`` can be omitted. Full signature example:: 101 102 def setType(self, ksp_type: KSP.Type | str) -> None: 103 104If a NumPy array is returned, use 105``ArrayBool``/``ArrayInt``/``ArrayReal``/``ArrayScalar`` as the return type. 106