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

[ayshih]

We have this code:

sunpy/sunpy/map/mapbase.py

Line 198 in ef9b401

cls.__doc__ += textwrap.indent(_notes_doc, " ")

that automatically appends a fresh "Notes" section with a couple of notes and a warning:

sunpy/sunpy/map/mapbase.py

Lines 83 to 105 in ef9b401

	Notes
	-----
	A number of the properties of this class are returned as two-value named
	tuples that can either be indexed by position ([0] or [1]) or be accessed
	by the names (.x and .y) or (.axis1 and .axis2). Things that refer to pixel
	axes use the ``.x``, ``.y`` convention, where x and y refer to the FITS
	axes (x for columns y for rows). Spatial axes use ``.axis1`` and ``.axis2``
	which correspond to the first and second axes in the header. ``axis1``
	corresponds to the coordinate axis for ``x`` and ``axis2`` corresponds to
	``y``.
	This class assumes that the metadata adheres to the FITS 4 standard.
	Where the CROTA2 metadata is provided (without PC_ij) it assumes a conversion
	to the standard PC_ij described in section 6.1 of .
	`Calabretta & Greisen (2002) <https://doi.org/10.1051/0004-6361:20021327>`_
	.. warning::
	If a header has CD_ij values but no PC_ij values, CDELT values are required
	for this class to construct the WCS.
	If a file with more than two dimensions is feed into the class,
	only the first two dimensions (NAXIS1, NAXIS2) will be loaded and the
	rest will be discarded.

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.

[ryuusama09]

We have this code:

sunpy/sunpy/map/mapbase.py

Line 198 in ef9b401

cls.__doc__ += textwrap.indent(_notes_doc, " ")

that automatically appends a fresh "Notes" section with a couple of notes and a warning:

sunpy/sunpy/map/mapbase.py

Lines 83 to 105 in ef9b401

	Notes
	-----
	A number of the properties of this class are returned as two-value named
	tuples that can either be indexed by position ([0] or [1]) or be accessed
	by the names (.x and .y) or (.axis1 and .axis2). Things that refer to pixel
	axes use the ``.x``, ``.y`` convention, where x and y refer to the FITS
	axes (x for columns y for rows). Spatial axes use ``.axis1`` and ``.axis2``
	which correspond to the first and second axes in the header. ``axis1``
	corresponds to the coordinate axis for ``x`` and ``axis2`` corresponds to
	``y``.
	This class assumes that the metadata adheres to the FITS 4 standard.
	Where the CROTA2 metadata is provided (without PC_ij) it assumes a conversion
	to the standard PC_ij described in section 6.1 of .
	`Calabretta & Greisen (2002) <https://doi.org/10.1051/0004-6361:20021327>`_
	.. warning::
	If a header has CD_ij values but no PC_ij values, CDELT values are required
	for this class to construct the WCS.
	If a file with more than two dimensions is feed into the class,
	only the first two dimensions (NAXIS1, NAXIS2) will be loaded and the
	rest will be discarded.

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.