Skip to content

Commit 5d8e440

Browse files
committed
Add table with built-in frames to docstring.
1 parent 1b69a9d commit 5d8e440

2 files changed

Lines changed: 51 additions & 11 deletions

File tree

‎astropy/coordinates/builtin_frames/__init__.py‎

Lines changed: 49 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -75,15 +75,15 @@
7575
from .lsr import LSR, LSRD, LSRK, GalacticLSR
7676

7777
# we define an __all__ because otherwise the transformation modules
78-
# get included
78+
# get included. Note that the order here determines the order in the
79+
# documentation of the built-in frames (see make_transform_graphs_docs).
7980
__all__ = [
8081
"ICRS",
8182
"FK5",
8283
"FK4",
8384
"FK4NoETerms",
8485
"Galactic",
8586
"Galactocentric",
86-
"galactocentric_frame_defaults",
8787
"Supergalactic",
8888
"AltAz",
8989
"HADec",
@@ -100,19 +100,38 @@
100100
"GeocentricTrueEcliptic",
101101
"BarycentricTrueEcliptic",
102102
"HeliocentricTrueEcliptic",
103-
"SkyOffsetFrame",
104-
"GalacticLSR",
103+
"HeliocentricEclipticIAU76",
104+
"CustomBarycentricEcliptic",
105105
"LSR",
106106
"LSRK",
107107
"LSRD",
108+
"GalacticLSR",
109+
"SkyOffsetFrame",
108110
"BaseEclipticFrame",
109111
"BaseRADecFrame",
112+
"galactocentric_frame_defaults",
110113
"make_transform_graph_docs",
111-
"HeliocentricEclipticIAU76",
112-
"CustomBarycentricEcliptic",
113114
]
114115

115116

117+
def _get_doc_header(cls):
118+
"""Get the first line of a docstring.
119+
120+
Skips possible empty first lines, and then combine following text until
121+
the first period or a fully empty line.
122+
"""
123+
out = []
124+
for line in cls.__doc__.splitlines():
125+
if line:
126+
parts = line.split(".")
127+
out.append(parts[0].strip())
128+
if len(parts) > 1:
129+
break
130+
elif out:
131+
break
132+
return " ".join(out) + "."
133+
134+
116135
def make_transform_graph_docs(transform_graph):
117136
"""
118137
Generates a string that can be used in other docstrings to include a
@@ -131,11 +150,16 @@ def make_transform_graph_docs(transform_graph):
131150
"""
132151
from textwrap import dedent
133152

134-
coosys = [transform_graph.lookup_name(item) for item in transform_graph.get_names()]
153+
coosys = {
154+
(cls := transform_graph.lookup_name(item)).__name__: cls
155+
for item in transform_graph.get_names()
156+
}
135157

136158
# currently, all of the priorities are set to 1, so we don't need to show
137159
# then in the transform graph.
138-
graphstr = transform_graph.to_dot_graph(addnodes=coosys, priorities=False)
160+
graphstr = transform_graph.to_dot_graph(
161+
addnodes=list(coosys.values()), priorities=False
162+
)
139163

140164
docstr = """
141165
The diagram below shows all of the built in coordinate systems,
@@ -183,7 +207,23 @@ def make_transform_graph_docs(transform_graph):
183207
"""
184208
docstr = docstr + dedent(graph_legend)
185209

186-
return docstr
210+
# Add table with built-in frame classes.
211+
template = """
212+
* - `~astropy.coordinates.{}`
213+
- {}
214+
"""
215+
table = """
216+
Built-in Frame Classes
217+
^^^^^^^^^^^^^^^^^^^^^^
218+
.. list-table::
219+
:widths: 20 80
220+
""" + "".join(
221+
template.format(name, _get_doc_header(coosys[name]))
222+
for name in __all__
223+
if name in coosys
224+
)
225+
226+
return docstr + dedent(table)
187227

188228

189229
_transform_graph_docs = make_transform_graph_docs(frame_transform_graph)

‎docs/coordinates/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -552,8 +552,8 @@ coordinate systems implemented here include:
552552
the True Equator Mean Equinox (TEME) coordinate frame.
553553

554554

555-
Built-in Frame Classes
556-
======================
555+
Built-in Frames and Transformations
556+
===================================
557557

558558
.. automodule:: astropy.coordinates.builtin_frames
559559

0 commit comments

Comments
 (0)