1*55a74a43SLisandro DalcinDocumentation standards for PETSc4py 2*55a74a43SLisandro Dalcin==================================== 3*55a74a43SLisandro Dalcin 4*55a74a43SLisandro DalcinSubject to exceptions given below, new contributions to PETSc4py **must** 5*55a74a43SLisandro Dalcininclude `type annotations <python:typing>` for function parameters and results, 6*55a74a43SLisandro Dalcinand docstrings on every class, function and method. 7*55a74a43SLisandro Dalcin 8*55a74a43SLisandro DalcinThe documentation should be consistent with the corresponding C API 9*55a74a43SLisandro Dalcindocumentation, including copying text where this is appropriate. More in-depth 10*55a74a43SLisandro Dalcindocumentation from the C API (such as extended discussions of algorithmic or 11*55a74a43SLisandro Dalcinperformance factors) should not be copied. 12*55a74a43SLisandro Dalcin 13*55a74a43SLisandro DalcinDocstring standards 14*55a74a43SLisandro Dalcin------------------- 15*55a74a43SLisandro DalcinDocstrings are to be written in `numpydoc:format` format. 16*55a74a43SLisandro Dalcin 17*55a74a43SLisandro DalcinThe first line of a function or method docstring must be a short description of 18*55a74a43SLisandro Dalcinthe method in imperative mood ("Return the norm of the matrix.") "Return" is 19*55a74a43SLisandro Dalcinto be preferred over "Get" in this sentence. A blank line must follow this 20*55a74a43SLisandro Dalcindescription. 21*55a74a43SLisandro Dalcin 22*55a74a43SLisandro DalcinIf the corresponding C API documentation lists a function as being collective, 23*55a74a43SLisandro Dalcinthen this information must be repeated on the next line of the docstring. E.g. 24*55a74a43SLisandro Dalcin"Not collective.", "Logically collective on X.", "Collective." 25*55a74a43SLisandro Dalcin 26*55a74a43SLisandro DalcinThe initial description section can contain more information if this is useful. 27*55a74a43SLisandro DalcinIn particular, if there is a PETSc manual chapter about a class, then this 28*55a74a43SLisandro Dalcinshould be referred to from here. 29*55a74a43SLisandro Dalcin 30*55a74a43SLisandro DalcinUse double backticks around literals (like strings and numbers). E.g. 31*55a74a43SLisandro Dalcin\`\`2\`\`, \`\`"foo"\`\`. 32*55a74a43SLisandro Dalcin 33*55a74a43SLisandro DalcinReference PETSc functions simply using backticks. eg: `petsc.KSP`. refers to 34*55a74a43SLisandro Dalcinthe PETSc C documentation for KSP. Do **not** use URLs in docstrings. Always 35*55a74a43SLisandro Dalcinuse Intersphinx references. 36*55a74a43SLisandro Dalcin 37*55a74a43SLisandro DalcinThe following sections describe the use of numpydoc sections. Other sections 38*55a74a43SLisandro Dalcinallowed by numpydoc may be included if they are useful. 39*55a74a43SLisandro Dalcin 40*55a74a43SLisandro DalcinParameters 41*55a74a43SLisandro Dalcin.......... 42*55a74a43SLisandro Dalcin 43*55a74a43SLisandro DalcinThis is required unless there are no parameters, or it will be completely 44*55a74a43SLisandro Dalcinobvious to even a novice user what the parameters do. 45*55a74a43SLisandro Dalcin 46*55a74a43SLisandro DalcinTypes should only be specified in this section if for some reason the types 47*55a74a43SLisandro Dalcinprovided by typing prove to be inadequate. If no type is being specified, do 48*55a74a43SLisandro Dalcinnot include a colon (``:``) to the right of the parameter name. 49*55a74a43SLisandro Dalcin 50*55a74a43SLisandro DalcinUse `Sys.getDefaultComm` when specifying the default communicator. 51*55a74a43SLisandro Dalcin 52*55a74a43SLisandro DalcinReturns 53*55a74a43SLisandro Dalcin....... 54*55a74a43SLisandro Dalcin 55*55a74a43SLisandro DalcinThis should only be specified if the return value is not obvious from the 56*55a74a43SLisandro Dalcininitial description and typing. 57*55a74a43SLisandro Dalcin 58*55a74a43SLisandro DalcinIf a "Returns" section is required, the type of the returned items *must* be 59*55a74a43SLisandro Dalcinspecified, even if this duplicates typing information. 60*55a74a43SLisandro Dalcin 61*55a74a43SLisandro DalcinSee Also 62*55a74a43SLisandro Dalcin........ 63*55a74a43SLisandro Dalcin 64*55a74a43SLisandro DalcinIf any of the following apply, then this section is required. The order of 65*55a74a43SLisandro Dalcinentries is as follows. Other links are permitted in this section if they add 66*55a74a43SLisandro Dalcininformation useful to users. 67*55a74a43SLisandro Dalcin 68*55a74a43SLisandro DalcinEvery ``setFromOptions`` must include the link \`petsc_options\`. 69*55a74a43SLisandro Dalcin 70*55a74a43SLisandro DalcinAny closely related part of the PETSc4py API not already linked in the 71*55a74a43SLisandro Dalcindocstring should appear (e.g. setters and getters should cross-refer). 72*55a74a43SLisandro Dalcin 73*55a74a43SLisandro DalcinIf there is a corresponding C API documentation page, this must be linked from 74*55a74a43SLisandro Dalcinthe "See also" section. E.g. \`petsc.MatSetValues\`. 75*55a74a43SLisandro Dalcin 76*55a74a43SLisandro DalcinEnd docstring with an empty line - "closing three quotation marks must be on a 77*55a74a43SLisandro Dalcinline by itself, preferably preceded by a blank line" 78*55a74a43SLisandro Dalcin 79*55a74a43SLisandro Dalcin.. warning:: 80*55a74a43SLisandro Dalcin 81*55a74a43SLisandro Dalcin The docstrings must not cause Sphinx warnings. 82*55a74a43SLisandro Dalcin 83*55a74a43SLisandro Dalcin 84*55a74a43SLisandro DalcinType hint standards 85*55a74a43SLisandro Dalcin------------------- 86*55a74a43SLisandro Dalcin 87*55a74a43SLisandro DalcinIf returning ``self``, use ``-> Self`` in function signature. 88*55a74a43SLisandro Dalcin 89*55a74a43SLisandro DalcinType hints are not required when the static type signature includes a PETSc 90*55a74a43SLisandro Dalcintype (e.g. ``Vec x``). These will be automatically generated. This will also 91*55a74a43SLisandro Dalcinwork for ``= None``. When using type hints, use spacing around the equals in 92*55a74a43SLisandro Dalcinany ``= None``. 93*55a74a43SLisandro Dalcin 94*55a74a43SLisandro DalcinCommunicators in type signatures must use Python typing instead of c-typing 95*55a74a43SLisandro Dalcin(i.e. ``comm: Comm`` not ``Comm comm``). This is because communicators 96*55a74a43SLisandro Dalcincan come from ``mpi4py`` and not just the ``petsc4py.PETSc.Comm`` class. 97*55a74a43SLisandro Dalcin 98*55a74a43SLisandro DalcinFor petsc4py native types that are can be strings, the type is ``argument: 99*55a74a43SLisandro DalcinKSP.Type | str`` (not eg: ``KSPType argument``). If the type is strictly an 100*55a74a43SLisandro Dalcinenum the ``| str`` can be omitted. Full signature example:: 101*55a74a43SLisandro Dalcin 102*55a74a43SLisandro Dalcin def setType(self, ksp_type: KSP.Type | str) -> None: 103*55a74a43SLisandro Dalcin 104*55a74a43SLisandro DalcinIf a NumPy is returned, use ``ArrayInt``/``ArrayReal``/``ArrayScalar`` as the 105*55a74a43SLisandro Dalcinreturn type. 106