1

I am trying to document my method using a standard format, but in my search I found many "standard" ways of documenting methods. My method is:

@staticmethod
def validateMasterAttribute(attribute):
    ...

and according to this official Python documentation I should document it like this:

@staticmethod
def validateMasterAttribute(attribute):
    """ Validate that the entered master attribute has all the required nodes

    Keyword arguments:
    attribute -- type lxml.etree._Element, it is the xml node for the master attribute

    Return:
    Nothing if the node contains all the required sub nodes. Otherwise, it throws a TagNotFoundException exception
    """
    ...

however, it is written in this question that I should document it like:

@staticmethod
def validateMasterAttribute(attribute):
    """

    Validate that the entered master attribute has all the required nodes
    :attribute: type lxml.etree._Element, it is the xml node for the master attribute
    return: Nothing if the node contains all the required sub nodes. Otherwise, it throws a TagNotFoundException exception
    """
    ...

I also found another docstring format, which seems old. What is the format that Sphinx can parse and generate web pages from?

Community
  • 1
  • 1
Marco Dinatsoli
  • 10,322
  • 37
  • 139
  • 253
  • There are several *"way of documentation"*, particularly if Sphinx is extended - [Numpy](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_numpy.html#example-numpy) and [Google](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html), for example. The PEP just defines how docstrings should be laid out within your code, you need to read e.g. the Sphinx documentation for how specifically they should be formatted for post-processing. – jonrsharpe Sep 07 '15 at 11:06
  • In fact, the PEP is pretty clear on this right at the top (emphasis mine): *"The aim of this PEP is to standardize the high-level structure of docstrings: what they should contain, and how to say it (**without touching on any markup syntax within docstrings**)."* – jonrsharpe Sep 07 '15 at 11:15

1 Answers1

0

You might want to consult Documenting Your Project Using Sphinx.

Alternatively you can use Napoleon which is an extension supporting google syntax for doctrings.

Choose one. Be consistent.

Vlad Mettler
  • 274
  • 3
  • 6