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