Add support for documenting a subclass of param.Parameterized

[Davide-sd]

Is your feature request related to a problem? Please describe.

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")
    d = param.ClassSelector(allow_None=True, class_=(list, tuple), doc="some docstring for parameter d")

    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  
d    None  ClassSelector             V RW AN 

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

a: some docstring for parameter a
b: some docstring for parameter b
c: some docstring for parameter c
d: some docstring for parameter d
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
..     autoattribute:: my_module.A.d
..     autofunction:: my_module.A.my_method

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

Describe the solution you'd like

I realize this is a big feature request. The problem of documenting subclasses of param.Parameterized can be tackled in several ways, each one offering its own advantage and requiring a certain amount of effort to be coded.

The first one: let autoattribute be aware of param. This would allow a user to document only attributes that are supposed to be used by the user, while keeping other attributes as private.

In a basic form, autoattribute should be able to extract the docstring from the parameter. In a more advanced form, it would be nice to be able to chose what to display. Parameters encode some type. For example, a is a boolean, b represents a number whose value is limited -10 < value < 10. d can be a list or tuple. This appears to be the beginning of a rabbit hole.

Describe alternatives you've considered

As an alternative, I would be happy enough to be able to show all parameters just after the class docstring, similarly to what is shown above when executing A?.

[electric-coder]

What syntax is this?

A?

---

The first one: let autoattribute be aware of param.

That should be a Sphinx extension because creating a dependency in Sphinx on 3rd party library syntax isn't a good design choice. You should post this FR at the param repo.

@Davide-sd see https://github.com/holoviz/param/issues/197