3

What is the standard way to document the type of function arguments and class attributes to differentiate between those that are expected to be instances of a class and those that are expected to be class objects themselves?

class TestClass(object):
    def __init__(self):
        pass

class Objectify(object):
    def __init__(self):
        pass    

class NeatDocumentation(object):
    """A class demonstrating neat documentation style.

    Attributes:
        cls (TestClass?): A class you want to test.
        obj (Objectify?): An instance of `Objectify` class.
        string (str): A string because why not.
    """

    def __init__(self, cls_, obj, string):
        self.cls = cls_  # An instance can be created by executing self.cls()
        self.obj = obj
        self.string = string
Shobhit
  • 773
  • 7
  • 20

1 Answers1

0

The python standard is the sphinx style which is using restructuredtext (http://www.sphinx-doc.org/en/1.4.9/rest.html)

More precisely, the autodoc module style: http://www.sphinx-doc.org/en/1.4.8/ext/autodoc.html

If you want to have prettier strings, you could also use the sphinx-napoleon style: http://www.sphinx-doc.org/en/1.4.9/ext/napoleon.html

In your case, you could do:

:param your_param: Class to test
:type your_param: :class:`Objectify`

Or using napoleon:

Args:
    your_param (Objectify): The :class:`Objectify` class to test
Pierre Barre
  • 2,174
  • 1
  • 11
  • 23
  • 1
    The correct syntax is `:py:class:` but this doesn't answer the question because OP is looking for the "rtype" style syntax (i.e. type-hinting) – Thiago Figueiro May 15 '18 at 05:07
  • He is not looking for `rtype` either. He is looking for the equivalent of `:py:class` for class 'type' instead of instances types. – stelios Aug 21 '18 at 14:22
  • All the links in this answer 404 now. – Todd Jan 16 '19 at 18:22