Improved param and rx docs

[MarcSkovMadsen]

Attempt to make .param, .rx and .rx() easier to use by improving docstrings.

Currently I meet a lot of dead ends because of missing or very sparse docstrings.

For example .rx in example below has no docstring which makes it almost impossible to use without already knowing how.

import param

class MyClass(param.Parameterized):
    value = param.Parameter()

my_class = MyClass(value=0)
rx_value = my_class.param.value.rx

Its the same for .param. There is no docstring.

I do believe it would help users tremendously if there where docstring and improved docstrings. It would make the .param and .rx namespaces so much more inviting and easy to use.

Guiding Principles

• Use Numpy style docstrings (would strongly prefer google docstrings because they are better as tooltips)
• Add types where they are easy to add
• Document in style similar to Panel docstrings
  • Reference link
  • Basic examples that can run
• Ok to make smaller refactors of code if they can be done without breaking changes.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 87.36%. Comparing base (1868240) to head (3237360).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #977   +/-   ##
=======================================
  Coverage   87.35%   87.36%           
=======================================
  Files           9        9           
  Lines        4935     4938    +3     
=======================================
+ Hits         4311     4314    +3     
  Misses        624      624           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[MarcSkovMadsen]

As I am not a regular contributor to param it would help me to get a review, feedback and merge of this "smaller" PR.

Then I would feel confident making a larger PR more systematically going through .param and .rx namespaces and improving the docstrings and types.

[hoxbro]

Thank you so much! Love it.

[hoxbro]

Let's see if @philippjfr has anything to say.

[maximlt]

I found inconsistencies in the formatting of the docstrings added in this PR. I also wonder if the links shouldn't point to the reference API instead of to the user guides.

Before merging, I'd recommend building the dev site from this branch and checking that the generated API ref is correctly formatted.

[philippjfr]

This is well overdue, so thanks for doing it. Let's make sure that we consistently use NumPy style docstrings though, right now this is an odd mix.

[MarcSkovMadsen]

This is well overdue, so thanks for doing it. Let's make sure that we consistently use NumPy style docstrings though, right now this is an odd mix.

If think I should investigate whether ruff or something else can validate this. I'm not using Numpy Docstrings very much. So I will fail at this.

[MarcSkovMadsen]

Thanks so much for the feedback. Will correct it ASAP.

[MarcSkovMadsen]

This is well overdue, so thanks for doing it. Let's make sure that we consistently use NumPy style docstrings though, right now this is an odd mix.

I've updated the docstrings. Also means the code blocks are now >>> prefixed.

[maximlt]

Thanks for the updates Marc!

I see that Panel also has its examples code doctest formatted (>>> <code>). What's your experience using this format? I know that it sometimes annoys me as copy/pasting it (from a website, a docstring tooltip in an IDE, etc.) doesn't always strip >>> so you have to manually remove them. IIRC the ipython interpreter strips them out but not the base python REPL. The advantage of this format is that it enables running doctest which might be a good idea. By the way, I have no strong opinion over all of that, just trying to gauge the user experience.

[MarcSkovMadsen]

I also think they are hard to copy. But I changed them because of request to use numpy docstrings. I believe that is the format.

[MarcSkovMadsen]

It is the format

[MarcSkovMadsen]

I believe I got the feedback from @maximlt above that >>> codestyle is not very helpful as its hard to copy examples. I agree.

So even though >>> is numpy docstyle. I plan to overrule this by restructuredText code blocks. Please let me know if you disagree @hoxbro , @philippjfr, @maximlt as implementing one style and then have to change it is a massive task. Thanks.

Alternative would be markdown code blocks. But numpy docstyle is rst.

[maximlt]

So even though >>> is numpy docstyle. I plan to overrule this by restructuredText code blocks.

Could you show what that format looks like in the code? I'd also like to know how it will end up being displayed:

• in VSCode
• in JupyterLab
• on the reference API of Param's website (you could just make a change to your branch, trigger a dev doc build from Github, and post a screenshot)

[MarcSkovMadsen]

So even though >>> is numpy docstyle. I plan to overrule this by restructuredText code blocks.

Could you show what that format looks like in the code? I'd also like to know how it will end up being displayed:

• in VSCode
• in JupyterLab
• on the reference API of Param's website (you could just make a change to your branch, trigger a dev doc build from Github, and post a screenshot)

I'm simply not prepared to do that work again. I tried to analyze situation when started doing this for Panel. And the learning is there is no way that works great. If you are happy with Panel I'll do it like that. That is what I can offer.

Panel seems to be using >>> from sampling 4 modules.

[maximlt]

I'm simply not prepared to do that work again. I tried to analyze situation when started doing this for Panel. And the learning is there is no way that works great. If you are happy with Panel I'll do it like that. That is what I can offer.

Ok sure I understand, this is all a bit of a mess.

So even though >>> is numpy docstyle. I plan to overrule this by restructuredText code blocks.

Could you show how you plan to change it with an example? For example, how will this docstring look like with the change you plan to make?

        """
        Return the serialized parameters of the Parameterized object.

        Parameters
        ----------
        subset : list, optional
            A list of parameter names to serialize. If None, all parameters will be serialized. Defaults to None.
        mode : str, optional
            The serialization format. By default, only 'json' is supported. Defaults to 'json'.

        Returns
        -------
        Any
            The serialized value.

        User Guide
        ----------
        https://param.holoviz.org/user_guide/Serialization_and_Persistence.html#serializing-with-json

        Examples
        --------
        Create a Parameterized instance and serialize its parameters:

        >>> import param
        >>> class P(param.Parameterized):
        >>>     a = param.Number()
        >>>     b = param.String()
        >>> p = P(a=1, b="hello")

        Serialize parameters:

        >>> serialized_data = p.param.serialize_parameters()
        >>> print(serialized_data)
        {"name": "P00002", "a": 1, "b": "hello"}
        """

Then I can look a little bit what would the user experience be on various platforms (VSCode, JLab, website, etc.).

---

Just linking something that I wasn't aware of, the sphinx-copybutton Sphinx extension has lots of ways to configure what gets copied in the end, possibly stripping out >>> : https://sphinx-copybutton.readthedocs.io/en/latest/use.html. I'm not sure why Pandas doesn't use that (check https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.sort_values.html).

[jbednar]

This looks very useful; thanks @MarcSkovMadsen !

[MarcSkovMadsen]

I'm simply not prepared to do that work again. I tried to analyze situation when started doing this for Panel. And the learning is there is no way that works great. If you are happy with Panel I'll do it like that. That is what I can offer.

Ok sure I understand, this is all a bit of a mess.

So even though >>> is numpy docstyle. I plan to overrule this by restructuredText code blocks.

Could you show how you plan to change it with an example? For example, how will this docstring look like with the change you plan to make?

        """
        Return the serialized parameters of the Parameterized object.

        Parameters
        ----------
        subset : list, optional
            A list of parameter names to serialize. If None, all parameters will be serialized. Defaults to None.
        mode : str, optional
            The serialization format. By default, only 'json' is supported. Defaults to 'json'.

        Returns
        -------
        Any
            The serialized value.

        User Guide
        ----------
        https://param.holoviz.org/user_guide/Serialization_and_Persistence.html#serializing-with-json

        Examples
        --------
        Create a Parameterized instance and serialize its parameters:

        >>> import param
        >>> class P(param.Parameterized):
        >>>     a = param.Number()
        >>>     b = param.String()
        >>> p = P(a=1, b="hello")

        Serialize parameters:

        >>> serialized_data = p.param.serialize_parameters()
        >>> print(serialized_data)
        {"name": "P00002", "a": 1, "b": "hello"}
        """

Then I can look a little bit what would the user experience be on various platforms (VSCode, JLab, website, etc.).

Just linking something that I wasn't aware of, the sphinx-copybutton Sphinx extension has lots of ways to configure what gets copied in the end, possibly stripping out >>> : https://sphinx-copybutton.readthedocs.io/en/latest/use.html. I'm not sure why Pandas doesn't use that (check https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.sort_values.html).

The below is how it looks in my version of VS Code on windows with pylance. I don't have the latest version of VS Code.

For me that is fine. It looks good. The >>> and ... are pasted too. But that is a Feature Request for VS Code/ Pylance to fix. We are using the "standard" numpy format.

vs-code.mp4

VS Code and jedi-language-server actually works better because it strips out the >>> and .... Both when shown and when copy-pasted. This is perfect.

vscode-jedi-language-server.mp4

[maximlt]

LGTM other than 1 pending suggestion. Let's preserve the original Numpy style for the examples, I think we can tweak the sphinx-copybutton extension to work in a decent way, and hopefully VSCode will make it easier to copy/paste these snippets. If we end up needing to change the style, it shouldn't be too hard to write a script to re-write the docstrings automatically, stripping >>> and ... (the other way around, yes!).

[maximlt]

@MarcSkovMadsen?