posit-dev / posit-dev/py-shiny

input_handler.input_handlers documentation appears misrendered

Open
#877 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

needs-triage
Dominant language
Python
Stars
1.8k
Forks
135
Avg merge
2d 18h
Merged PRs (30d)
21

Description

The documentation provided in the source code for input_handler.input_handlers appears to be misrendered on the website:

  • The initial paragraphs, which provide a description, are missing.
  • The methods table renders as a paragraph, but seems intended to be a table.

Here is the source code:

input_handlers.__doc__ = """
Manage Shiny input handlers.

Add and/or remove input handlers of a given ``type``. Shiny uses these handlers to
pre-process input values from the client (after being deserialized) before passing them
to the ``input`` argument of an :func:`~shiny.App`'s ``server`` function.

The ``type`` is based on the ``getType()`` JavaScript method on the relevant Shiny
input binding. See `this article <https://shiny.posit.co/articles/js-custom-input.html>`_
for more information on how to create custom input bindings. (The article is about
Shiny for R, but the JavaScript and general principles are the same.)

Methods
--------
add(type: str, force: bool = False) -> Callable[[InputHandlerType], None]
    Register an input handler. This method returns a decorator that registers the
    decorated function as the handler for the given ``type``. This handler should
    accept three arguments:
    - the input ``value``
    - the input ``name``
    - the :class:`~shiny.Session` object
remove(type: str)
    Unregister an input handler.

Note
----
``add()`` ing an input handler will make it persist for the duration of the Python
process (unless Shiny is explicitly reloaded). For that reason, verbose naming is
encouraged to minimize the risk of colliding with other Shiny input binding(s) which
happen to use the same ``type`` (if this the binding is bundled with a package, we
recommend the format of "packageName.widgetName").

Example
-------
```{python}
#| eval: false
from shiny.input_handler import input_handlers
@input_handlers.add("mypackage.intify")
def _(value, name, session):
    return int(value)
```

On the Javascript side, the associated input binding must have a corresponding
``getType`` method:

```{python}
#| eval: false
getType: function(el) {
    return "mypackage.intify";
}
```
"""

Here is what appears on the website:
Screenshot 2023-12-07 at 4 31 45 PM

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the input_handlers docstring in shiny/input_handler.py around line 42 and compare it with the rendered input_handler.input_handlers page. Investigate the documentation renderer's handling of the docstring's paragraphs and Methods section, then verify that the description appears and the methods render as a table on the website.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.