streamlit / docs

Source code for the Streamlit Python library documentation
https://docs.streamlit.io
Apache License 2.0
111 stars 461 forks source link

Autofunction: Let class docstring override @property functions #1092

Closed sfc-gh-dmatthews closed 3 months ago

sfc-gh-dmatthews commented 3 months ago

📚 Context

When the docstring parser creates the dictionary for a class in streamlit.json, @property-decorated functions get saved under the "property" key. Any "Attributes" in the docstring get saved under the "args" key. When Autofunction renders a class, the "properties" and "args" are combined under the "Attribute" header. Up until now, a class attribute was not recorded in "Attributes" if it existed as an @property-decorated method, to avoid duplicates.

This PR is needed to better support the StreamlitPage class for 1.36.0.

🧠 Description of Changes

This PR includes a check for duplicate attributes for classes. If an attribute exists in both the docstring "Attributes" list and as a @property-decorated function, Autofunction will only render the attribute from the docstring.

When an @property attribute is rendered, it includes an anchor link, expecting another Autofunction below to render the method. Not all attributes exists as @property-decorated functions that can be picked up automatically, and not all @property-decorated functions need to be fully rendered with their own Autofunction. Therefore, this PR gives the ability to override the automatic detection of @property-decorated methods.

This doesn't impact the current instances where "Attributes" in the docstring supplement the @property-decorated methods. (e.g. AppTest)

Contribution License Agreement By submitting this pull request you agree that all contributions to this project are made under the Apache 2.0 license.

sfc-gh-dmatthews commented 3 months ago

I will merge this singe-commit PR without squashing to simplify things. (I merged this commit into release instead of cherry-pick, so if it gets merged into main without squashing I won't have to revert it on release branch or deal with the conflict.)

snehankekre commented 3 months ago

LGTM and is a good addition!