CODEWITHSUNDEEP
pythonparameterspython-sphinxholoviz
Davide_sd
Davide_sd

Reputation: 13170

Sphinx - How to document a subclass of param.Parameterized

One of param's main advantage is that of simplifying the codebase.

Let's consider this toy class:

import param

class A(param.Parameterized):
    """This is my docstring.
    """

    a = param.Boolean(True, doc="some docstring for parameter a")
    b = param.Number(1, bounds=(-10, 10), doc="some docstring for parameter b")
    c = param.Boolean(False, readonly=True, doc="some docstring for parameter c")

    def __init__(self, a, b, **kwargs):
        super().__init__(a=a, b=b, **kwargs)

    def my_method(self):
        "my method docstring"
        pass

While working on Jupyter Notebook, I can read the class docstring with:

A?

which outputs:

Init signature: A(a, b, **kwargs)
Docstring:     
This is my docstring.
    
Parameters of 'A'
=================

Parameters changed from their default values are marked in red.
Soft bound values are marked in cyan.
C/V= Constant/Variable, RO/RW = ReadOnly/ReadWrite, AN=Allow None

Name Value    Type     Bounds   Mode 

a    True  Boolean             V RW 
b     1     Number  (-10, 10)  V RW 
c   False  Boolean             C RO 

Parameter docstrings:
=====================

a: some docstring for parameter a
b: some docstring for parameter b
c: some docstring for parameter c
Type:           ParameterizedMetaclass
Subclasses:

This is great, because we can immediatly understand what parameters are available and what they are supposed to do.

However, we may need to create an html documentation (with Sphinx) of a module containing subclasses of param.Parameterized. So far, I tried Sphinx autodoc. In the file my_module.rst I wrote:

.. module:: my_module

.. autoclass:: A

..     autoattribute:: my_module.A.a
..     autoattribute:: my_module.A.b
..     autoattribute:: my_module.A.c
..     autofunction:: my_module.A.my_method

However, autoattribute is unable to extract the docstring from the parameters.

For people regularly using param, how do you create html documentation of your applications/modules? Is there any way to get autodoc to extract those docstring? Or are there any sphinx extensions that helps process subclasses of param.Parameterized?

Upvotes: 4

Views: 31

Answers (0)

Related Questions