Docstring for class, method and function

• Documentation of the API is generated automatically when a release is tagged

• It is available at https://in2p3-readout400.pages.in2p3.fr/software/<project name>

• The documentation generator is sphinx. Submodule(s), class(es) and function(s) are discovered automatically via the sphinx extension autodoc2

• Each class, method and function must have a docstring unless it meets all of the following criteria:

  • not externally visible

  • very short

  • obvious

• Example for a function or a method:

  
      def example_function(param1: str, param2: int) -> bool:
          """The summary line for function docstring should fit on one line.
  
          Note:
              * Multiple line are supported for the description of parameters.
  
          Args:
              param1: The first parameter.
              param2: The second parameter.
  
          Returns:
              True if successful, False otherwise.
  
              * The return type is optional and may be specified at the beginning
                of the ``Returns`` section followed by a colon.
  
              * The ``Returns`` section may span multiple lines and paragraphs.
                Following lines should be indented to match the first line.
  
              * The ``Returns`` section supports any reStructuredText formatting,
                including literal blocks::
  
                          {
                              "attr1": "val1",
                              "attr2": "val2"
                          }
  
          """
          return True
  

• We adopt:

  • The Google style python docstring!

  • For class, the init method has to be documented in the class level

  • The type of function (method) arguments is defined in the signature by using Python type hints (python 3.9 and 3.10)

  • The type of class attributes is specified in the init docstring of the class

  • Example for a python class: p400collection/collection.py

  • More Example in sphinx documentation, be careful since they don’t use python type hints.