posit-dev / posit-dev/py-shiny

Descriptions are not being passed to documentation page for types

Open
#875 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

Many of the items documented at https://shiny.posit.co/py/api/MiscTypes.html have descriptions in the source code, but these descriptions do not appear in the function reference, even though other elements of the documentation do.

For example, the source code for types.ImgData includes

class ImgData(TypedDict):
    """
    Return type for :func:`~shiny.render.image`.

    See Also
    --------
    ~shiny.render.image

    Example
    -------
    See :func:`~shiny.render.image`.
    """

    src: str
    """The ``src`` attribute of the ``<img>`` tag."""
    width: NotRequired[str | float]
    """The ``width`` attribute of the ``<img>`` tag."""
    height: NotRequired[str | float]
    """The ``height`` attribute of the ``<img>`` tag."""
    alt: NotRequired[str]
    """The ``alt`` attribute of the ``<img>`` tag."""
    style: NotRequired[str]
    """The ``style`` attribute of the ``<img>`` tag."""
    coordmap: NotRequired[Any]
    """TODO """

but the description in the first line does not appear in the rendered documentation:

Screenshot 2023-12-07 at 3 30 05 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 shiny/types.py and compare the ImgData source docstrings with the rendered MiscTypes.html entry for shiny.types.ImgData. Trace the documentation build path that produces this page and run it locally; done means the type and field descriptions shown in the source appear in the generated function reference.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.