GenericMap now passes docstrings to its subclasses

[asinghgaba]

Description

Helps GenericMap to pass its docstring to its subclasses.
Fixes #3716

[pep8speaks]

Hello @asinghgaba! Thanks for updating this PR.

• In the file sunpy/map/mapbase.py:

Line 2510:101: E501 line too long (223 > 100 characters)
Line 2257:101: E501 line too long (103 > 100 characters)
Line 2175:101: E501 line too long (103 > 100 characters)
Line 1975:101: E501 line too long (121 > 100 characters)
Line 1872:101: E501 line too long (139 > 100 characters)
Line 1717:101: E501 line too long (109 > 100 characters)
Line 1660:101: E501 line too long (106 > 100 characters)
Line 1659:101: E501 line too long (108 > 100 characters)
Line 1616:101: E501 line too long (114 > 100 characters)
Line 1247:101: E501 line too long (111 > 100 characters)
Line 1032:101: E501 line too long (109 > 100 characters)
Line 1031:101: E501 line too long (131 > 100 characters)
Line 34:101: E501 line too long (109 > 100 characters)

Comment last updated at 2021-04-28 19:33:35 UTC

[dstansby]

I think this is a change in behaviour, not a trivial fix, so I've milestoned for 3.0 instead of backporting.

[dstansby]

Looks good to me - I'm happy to approve when @ayshih suggested change to the order has been made.

[ayshih]

I think the output from the PR is confusing (example for CORMap):

• The initial docstring of GenericMap ("A Generic spatially-aware 2D data array") is not stripped out or otherwise prefaced.
• The example in the docstring GenericMap is not stripped out, which means that every non-AIAMap class shows an example of using AIAMap. (As an aside, why does the docstring for GenericMap not show GenericMap?)

This demonstrates that we can't do a simple string addition. There needs to be a deeper level of refactoring so that docstring elements can be re-used in the docstrings of both GenericMap and the subclasses.

[asinghgaba]

@ayshih I think this should be done by adding docstrings individually to each subclass. We could then strip as much we want according to the subclass. What do you think about doing it this way?

[ayshih]

I (mostly) disagree. We want the creation of the merged docstring to be under GenericMap to facilitate maintenance and to ensure a standard presentation. A person creating a new GenericMap subclass should be able to write a simple docstring, and have the merged docstring be automatically created. If we want to support customization for unusual situations, GenericMap.__init_subclass__ can call an overridable class method (e.g., _make_docstring().

[dstansby]

What do people think of adding some text along the lines of

For more information on map attributes and methods, see documentation for sunpy.map.GenericMap

instead? That way there's still a clear distinction between the docstrings of the two classes, but anyone using help(MyMapSource) has a pointer to GenericMap.

[nabobalis]

I wonder if we want to either do that or break up the important part of the Generic Map docstring and append that. Similar to how we do that with Fido Clients.

[Cadair]

Rather than taking this approach why not do something similar to what we do in coordinates, where the parameters are templated into the docstrings? Splitting up docstrings on magic sequences feels prone to hard to detect issues to me.

[nabobalis]

Final result: https://sunpy--5122.org.readthedocs.build/en/5122/api/sunpy.map.sources.AIAMap.html#aiamap

There is a double notes section but I think the separation is important?

PR rewritten

[Cadair]

I don't think the double notes section is an issue, but I am kinda surprised that sphinx doesn't get angry about that, I feel like old numpydoc would have done lol.

[nabobalis]

Thanks for getting us started on this @asinghgaba!