Skip to content

Lost class descriptions since 3.4 docs #20583

Closed

Description

@pp-mo

Problem

Key docstring information no longer appearing in v3.4 docs

Some class docstrings are omitted from the API pages,
making certain features virtually incomprehensible.

For instance ...

It seems that up to 3.3, the class matplotlib.colors.SymLogNorm had a nice description,
https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.colors.SymLogNorm.html
But it has since vanished.
https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.SymLogNorm.html#matplotlib.colors.SymLogNorm

All this key description is missing ...

The symmetrical logarithmic scale is logarithmic in both the positive and negative directions from the origin.
Since the values close to zero tend toward infinity, there is a need to have a range around zero that is linear. The parameter linthresh allows the user to specify the size of this range (-linthresh, linthresh).

linthresh: The range within which the plot is linear (to avoid having the plot go to infinity around zero).

linscale: This allows the linear range (-linthresh to linthresh) to be stretched relative to the logarithmic range. Its value is the number of decades to use for each half of the linear range. For example, when linscale == 1.0 (the default), the space used for the positive and negative halves of the linear range will be equal to one decade in the logarithmic range. Defaults to 1.

This occurs also for other classes, and not just in this module :
E.G. matplotlib.collections.RegularPolyCollection :
https://matplotlib.org/stable/api/collections_api.html?highlight=circumscribing#matplotlib.collections.RegularPolyCollection
( old version : https://matplotlib.org/3.1.1/api/collections_api.html#matplotlib.collections.RegularPolyCollection )
And this one is, I think, very important descriptive information that is no longer available

but certainly not all of them, e.g. LinearSegmentedColormap
https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.LinearSegmentedColormap.html#matplotlib.colors.LinearSegmentedColormap
(which is fine)

In fact, this last one is interesting, because it shows that the class docstring and the __init__ docstring have been combined into a single paragraph.
This leads me to guess that, just maybe, nothing appears when the class has a class docstring but no __init__ docstring.

I have tried to understand at what point this went wrong,
but unfortunately it's all rather beyond my understanding of Sphinx and schemes.

Suggested Improvement

Need to re-instate the missing docstring descriptions into the API documentation build.

Matplotlib version

  • Operating system: linux
  • Matplotlib version : -
  • Matplotlib documentation version (is listed under the logo): 3.4.2

Activity

  1. added this to the v3.4-doc milestone on Jul 6, 2021
  2. jklymak commented on Jul 6, 2021

    @jklymak
    Member

    @anntzer is this because of _make_norm_from_scale?

  3. tacaswell commented on Jul 6, 2021

    @tacaswell
    Member

    still broken in: https://matplotlib.org/devdocs/api/_as_gen/matplotlib.colors.SymLogNorm.html#matplotlib.colors.SymLogNorm

    This may be due to changes in CPython. Around 3.9 there was some changes to the way docstings got inherited / merged (see https://bugs.python.org/issue40257 for one entry point into that discussion), but @jklymak 's suggestion seems more likely.

  4. QuLogic commented on Jul 7, 2021

    @QuLogic
    Member

    This occurs also for other classes, and not just in this module :
    E.G. matplotlib.collections.RegularPolyCollection :
    https://matplotlib.org/stable/api/collections_api.html?highlight=circumscribing#matplotlib.collections.RegularPolyCollection
    ( old version : https://matplotlib.org/3.1.1/api/collections_api.html#matplotlib.collections.RegularPolyCollection )
    And this one is, I think, very important descriptive information that is no longer available

    I'm not sure what you mean; there's nothing missing from this one?

  5. anntzer commented on Jul 7, 2021

    @anntzer
    Contributor

    For make_norm_from_scale it looks like this likely comes from python/cpython@08b47c3 not fully reverting python/cpython@fbf2786 (e.g. in pydoc.py), although I am not certain of the exact call chain. A simple repro is

    In [1]: class A: "doc"
    
    In [2]: class B(A): pass
    
    In [3]: inspect.getdoc(B)
    Out[3]: 'doc'
    
    In [4]: help(B)  # doesn't show "doc"
    

    In any case, a simple enough fix is likely to explicitly inherit the docstring with

    diff --git i/lib/matplotlib/colors.py w/lib/matplotlib/colors.py
    index e0c42c5b69..ded57b320e 100644
    --- i/lib/matplotlib/colors.py
    +++ w/lib/matplotlib/colors.py
    @@ -1500,6 +1500,7 @@ def _make_norm_from_scale(scale_cls, base_norm_cls=None, *, init=None):
         Norm.__name__ = base_norm_cls.__name__
         Norm.__qualname__ = base_norm_cls.__qualname__
         Norm.__module__ = base_norm_cls.__module__
    +    Norm.__doc__ = base_norm_cls.__doc__
         Norm.__init__.__signature__ = bound_init_signature.replace(parameters=[
             inspect.Parameter("self", inspect.Parameter.POSITIONAL_OR_KEYWORD),
             *bound_init_signature.parameters.values()])

    Brownie points for anyone who makes a PR out of this.

  6. QuLogic commented on Jul 7, 2021

    @QuLogic
    Member

    I'm just waiting for sphinx to finish to confirm that that will fix it.

  7. pp-mo commented on Jul 7, 2021

    @pp-mo
    Author

    @QuLogic I'm not sure what you mean; there's nothing missing from this one?

    Sorry, I think I was wrong about that one.
    It has lost a bit of explanatory test, but not for this reason I think.

  8. modified the milestones: v3.4-doc, v3.4.3 on Jul 7, 2021
  9. pp-mo commented on Jul 7, 2021

    @pp-mo
    Author

    Checked it out : problem where I saw it is now fixed.
    Thanks @tacaswell @QuLogic @anntzer @jklymak -- awesome speed of response !
    🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions