Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rename 'Attributes' to 'Parameters' to fix documentation formatting #2901

Conversation

binste
Copy link
Contributor

@binste binste commented Feb 19, 2023

With the addition of method-based attribute setting in #2795, Sphinx started generate the documentation differently for the encoding channels. The documentation for attributes is now the first sentence of the documentation which is defined by _PropertySetter:

image

This is much less informative then what is in the docstring of altair.X and which would be shown otherwise:

    Attributes
    ----------

    shorthand : string
        shorthand for field, aggregate, and type
    aggregate : :class:`Aggregate`
        Aggregation function for the field (e.g., ``"mean"``, ``"sum"``, ``"median"``,
        ``"min"``, ``"max"``, ``"count"`` ).

        **Default value:** ``undefined`` (None)

        **See also:** `aggregate <https://vega.github.io/vega-lite/docs/aggregate.html>`__
        documentation.
    axis : anyOf(:class:`Axis`, None)
        An object defining properties of axis's gridlines, ticks and labels. If ``null``,
        the axis for the encoding channel will be removed.

        **Default value:** If undefined, default `axis properties
        <https://vega.github.io/vega-lite/docs/axis.html>`__ are applied.

        **See also:** `axis <https://vega.github.io/vega-lite/docs/axis.html>`__
        documentation.

I tried to disable this behavior but didn't find a way. However, I'd suggest to tackle the root cause of this directly instead of trying to reconfigure Sphinx. Following the numpydoc style for docstrings (see also ExampleError on this page), what is called Attributes in the Altair class docstrings should, in my understanding, be called Parameters as we document what parameters can be passed to e.g. altair.X and not what attributes it has after instantiation. As all Parameters usually also appear as Attributes (with the exception of the ones which are now replaced by the property-based methods) this didn't matter much so far. I'd suggest to now introduce this distinction by replacing Attributes with Parameters in the docstrings:

    Parameters
    ----------

    shorthand : string
        shorthand for field, aggregate, and type

After this change, the documentation renders again how it's supposed to:

image

@mattijn
Copy link
Contributor

mattijn commented Feb 19, 2023

Good find!

Copy link
Contributor

@joelostblom joelostblom left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another great addition, thank you!

@joelostblom joelostblom merged commit ef8ff94 into vega:master Feb 19, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants