Map subclass page in docs can have two "Notes" sections

[ayshih]

We have this code: https://github.com/sunpy/sunpy/blob/ef9b401913042bc20ae017a9a22e80ef735ad5bb/sunpy/map/mapbase.py#L198 that automatically appends a fresh "Notes" section with a couple of notes and a warning: https://github.com/sunpy/sunpy/blob/ef9b401913042bc20ae017a9a22e80ef735ad5bb/sunpy/map/mapbase.py#L83-L105

However, if the subclass docstring already has a "Notes" section, that means that the page in the docs will have two "Notes" sections (e.g., https://docs.sunpy.org/en/v5.1.1/generated/api/sunpy.map.sources.AIAMap.html). (Also, the "Notes" section is supposed to come before the "References" and Examples" sections, so blanket appending a "Notes" section can result in out-of-order sections, even if the subclass docstring does not already have a "Notes" section.)

We should try to do something more sophisticated, such as searching for the best point of insertion in to the docstring.

[cmdCrusaderr]

hey @ayshih could you please fix the link https://docs.sunpy.org/en/v5.0.1/generated/api/sunpy.map.sources.AIAMap.html , it's broken

[nabobalis]

hey @ayshih could you please fix the link docs.sunpy.org/en/v5.0.1/generated/api/sunpy.map.sources.AIAMap.html , it's broken

That version is outdated and was unlinked, try https://docs.sunpy.org/en/v5.1.1/generated/api/sunpy.map.sources.AIAMap.html

[ryuusama09]

We have this code:

https://github.com/sunpy/sunpy/blob/ef9b401913042bc20ae017a9a22e80ef735ad5bb/sunpy/map/mapbase.py#L198

that automatically appends a fresh "Notes" section with a couple of notes and a warning: https://github.com/sunpy/sunpy/blob/ef9b401913042bc20ae017a9a22e80ef735ad5bb/sunpy/map/mapbase.py#L83-L105

However, if the subclass docstring already has a "Notes" section, that means that the page in the docs will have two "Notes" sections (e.g., https://docs.sunpy.org/en/v5.1.1/generated/api/sunpy.map.sources.AIAMap.html). (Also, the "Notes" section is supposed to come before the "References" and Examples" sections, so blanket appending a "Notes" section can result in out-of-order sections, even if the subclass docstring does not already have a "Notes" section.)

We should try to do something more sophisticated, such as searching for the best point of insertion in to the docstring.

if notes >> references ... what is the other best point of insertion ? if the docstring doesnt have any other sections except for notes , references and warning .. then it should be straightforward prepending right ?

[nabobalis]

if notes >> references ... what is the other best point of insertion ? if the docstring doesnt have any other sections except for notes , references and warning .. then it should be straightforward prepending right ?

There is already an open PR for this. I would suggest another issue.