Create sphinx autodoc extension for param

[ceball]

We are already doing things to make param work well with sphinx, but I think if possible we should capture that into a sphinx autodoc extension.

Would make it easier for others to use (e.g. see ioam/ioam-builder#3).

[jlstevens]

I agree the extension should be supported at the param level instead of wherever it lives right now...

[tonyfast]

This would be great to have! Who knows how to do it? Smells like this would entail making a param/sphinx extension.

[Jhsmit]

@jlstevens is there a way to generate docs from params right now? In whatever form?

[philippjfr]

nbsite does have a paramdoc Sphinx extension. I've improved it a fair bit but it's still not great. This would be of huge value if someone were to pick it up and improve it. I also agree it should move into the param repo.

[Jhsmit]

I've made a mock project where I use an adaptation of the paramdoc extension in case anyone finds that useful: https://github.com/Jhsmit/param_docs

Basically the idea is to make the output as readable as possible for non-experts who just want to use the GUI.
Output is here: https://param-doc.readthedocs.io/en/latest/modules.html#module-param_docs.controller

[jlstevens]

@Jhsmit That output looks pretty good!

I think the param sphinx extension would ideally be in its own repo. I don't know how @jbednar or @philippjfr feel about this, but if @Jhsmit is willing to be a maintainer, this could be moved to pyviz-dev...

[Jhsmit]

I would be happy to be a maintainer, however I find myself wanting to contribute several parts of panel but I never find the time to do so. The mock project I made above is mostly driven by needing it for my own applications. So I can't guarantee any time investment.

[jbednar]

Wow, that looks great! Minor nitpick -- would be nice to have some whitespace/newlines between class definitions:

It was really helpful to show what happens to both Parameterized and non-Parameterized classes. Could you show examples for ParameterizedFunctions and for a Parameterized whose constructor accepts a non-Parameter arg and kwarg? E.g. what happens for code like:

class FruitStallController(param.Parameterized):
    def __init__(self, posarg=False, kwarg=5, **params):
        super(FruitStallController, self).__init__(**params)

class fn(param.ParameterizedFunction):
      a = param.Integer(3)
      def __call__(self, b, **kw):
          return self.a*b

[jbednar]

I think the param sphinx extension would ideally be in its own repo.

Is there some reason not to have that in the Param repo?

[jlstevens]

Is there some reason not to have that in the Param repo?

Sure. That does at least make more sense than shipping it with nbsite!

[Jhsmit]

@jbednar Good point this indeed needs some whitespace in between.
At the moment I assume the numpydoc extension is used as well (havent tested without it yet) and if the class is a subclass of ParameterizedMetaclass (both Parameterized and ParameterizedFunction) they get treated the same way, and normal numpydoc style formatting is supressed in favour of documenting only Parameters.

This might not be wanted behavior for the general use-case so maybe it should be configurable. What I was aiming for is to document only what users see in the GUI, so internally used args kwargs are ignored.

I suspect that a separate repo might make configuration for users easier when its a full sphinx extension rather then a module within Param. When its a sphinx extension, the configuration would be the more general:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode',
    'numpydoc',
    'paramdoc'
]

compared to

def setup(app):
    app.connect("autodoc-process-docstring", param_format_basic, priority=-100)

Although I dont know how sphinx extensions work exactly.

[jbednar]

normal numpydoc style formatting is supressed in favour of documenting only Parameters.

Makes sense. In my own work I rarely use anything but Parameters on a Parameterized, but that seems like an issue for a tool like HoloViews, where there is always a positional argument "data" followed by parameters. In that case the data argument would never get documented, so it's definitely important to make that behavior be configurable.

I don't know much about how sphinx extensions work either, but I would assume that it's not the repo that would matter, it's the packaging. I.e. surely the sphinx extension can live in the same param github repo in a subdirectory, even if it's shipped to the user as a sphinx extension installed separately.