How can I create documentation similar to a number?

Question

I work a lot with spyder and the object inspector, which is very convenient for me as an instant help function. Some modules seem to benefit very well from this feature. For example, the fairly simple numpy function (numpy.absolute) creates the following view in the object inspector:

I want to know how I can write my own modules in such a way that such a beautiful view is created when I call my functions in spyder.

Answer 1

For your documentation to display as well as the numpy number, you need to follow the NumpyDoc standard. Suppose you have a function called func with two arguments like this:

 def func(arg1, arg2): return True 

To add documentation to it, you need to write a multi-line string under its definition (called in the docstring of the Python world), for example

 def func(arg1, arg2): """Summary line. Extended description of function. Parameters ---------- arg1 : int Description of arg1 arg2 : str Description of arg2 Returns ------- bool Description of return value Examples -------- >>> func(1, "a") True """ return True 

What Spyder does is that it takes this simple text description, parses it and displays it as html, and finally shows it in the object inspector.

To see this, you just need to call func elsewhere in your code and press Ctrl + i next to it, for example:

 func<Ctrl+i>(1, "a") 

It also displays automatically when you write the left bracket next to func .

Answer 2

If your Python project (or file) is already documented by another type (like reStructuredText or Epytext ) or not documented, you can generate / convert docstrings to NumpyDoc style using Pyment :

 pyment -o numpydoc /my/python/project 

Please note that the previous command, launched after the installation of Pyment, will generate patches that should be applied to your code.

After your project is documented using the Numpydoc style, you can use the Sphinx extension to create your good, readable NumpyDoc style documentation!