mirror/astronomy
1
0
Fork 0
mirror of https://github.com/cosinekitty/astronomy.git synced 2026-04-04 14:55:38 -04:00
Code Issues Packages Projects Releases Wiki Activity

Python docs: support documentation of enumerated types.

Browse Source
This commit is contained in:
Don Cross
2019-07-12 19:58:14 -04:00
parent 033a2a1b53
commit f97096105a
4 changed files with 289 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
generate/template/astronomy.py
View File

@@ -85,41 +85,35 @@ class Vector:
@enum.unique
class Body(enum.IntEnum):
"""The celestial bodies supported by Astronomy Engine calculations.
Values
------
Invalid: An unknown, invalid, or undefined celestial body.
Mercury: The planet Mercury.
Venus: The planet Venus.
Earth: The planet Earth.
Mars: The planet Mars.
Jupiter: The planet Jupiter.
Saturn: The planet Saturn.
Uranus: The planet Uranus.
Neptune: The planet Neptune.
Pluto: The planet Pluto.
Sun: The Sun.
Moon: The Earth's moon.
"""
Invalid = -1
"""A placeholder value for an unknown, undefined, or invalid body."""
Mercury = 0
"""The body code for the planet Mercury."""
Venus = 1
"""The body code for the planet Venus."""
Earth = 2
"""The body code for the planet Earth."""
Mars = 3
"""The body code for the planet Mars."""
Jupiter = 4
"""The body code for the planet Jupiter."""
Saturn = 5
"""The body code for the planet Saturn."""
Uranus = 6
"""The body code for the planet Uranus."""
Neptune = 7
"""The body code for the planet Neptune."""
Pluto = 8
"""The body code for the planet Pluto."""
Sun = 9
"""The body code for the Sun."""
Moon = 10
"""The body code for the Moon."""
def BodyCode(name):
"""Finds the Body enumeration value, given the name of a body.
@@ -343,9 +337,14 @@ class Time:
class Observer:
"""Represents the geographic location of an observer on the surface of the Earth.
:param latitude: Geographic latitude in degrees north of the equator.
:param longitude: Geographic longitude in degrees east of the prime meridian at Greenwich, England.
:param height: Elevation above sea level in meters.
Parameters
----------
latitude : float
Geographic latitude in degrees north of the equator.
longitude : float
Geographic longitude in degrees east of the prime meridian at Greenwich, England.
height : float
Elevation above sea level in meters.
"""
def __init__(self, latitude, longitude, height=0):
self.latitude = latitude
@@ -1018,6 +1017,18 @@ def Equator(body, time, observer, ofdate, aberration):
@enum.unique
class Refraction(enum.IntEnum):
"""Selects if/how to correct for atmospheric refraction.
Some functions allow enabling or disabling atmospheric refraction
for the calculated apparent position of a celestial body
as seen by an observer on the surface of the Earth.
Values
------
Airless: No atmospheric refraction correction.
Normal: Recommended correction for standard atmospheric refraction.
JplHorizons: Used only for compatibility testing with JPL Horizons online tool.
"""
Airless = 0
Normal = 1
JplHorizons = 2
@@ -1646,6 +1657,17 @@ def SearchHourAngle(body, observer, hourAngle, startTime):
@enum.unique
class Direction(enum.IntEnum):
"""Indicates whether a body is rising above or setting below the horizon.
Specifies the direction of a rising or setting event for a body.
For example, `Direction.Rise` is used to find sunrise times,
and `Direction.Set` is used to find sunset times.
Values
------
Rise: First appearance of a body as it rises above the horizon.
Set: Last appearance of a body as it sinks below the horizon.
"""
Rise = +1
Set = -1
@@ -1766,6 +1788,19 @@ def _distance_slope(direction, time):
@enum.unique
class ApsisKind(enum.IntEnum):
"""Represents whether a satellite is at a closest or farthest point in its orbit.
An apsis is a point in a satellite's orbit that is closest to,
or farthest from, the body it orbits (its primary).
`ApsisKind` is an enumerated type that indicates which of these
two cases applies to a particular apsis event.
Values
------
Pericenter: The satellite is at its closest point to its primary.
Apocenter: The satellite is at its farthest point from its primary.
Invalid: A placeholder for an undefined, unknown, or invalid apsis.
"""
Pericenter = 0
Apocenter = 1
Invalid = 2

63
pydown/pydown.py
View File

@@ -50,6 +50,7 @@ class DocInfo:
self.description = ''
self.parameters = []
self.attributes = []
self.enumValues = []
lines = doc.split('\n')
@@ -66,7 +67,7 @@ class DocInfo:
for line in lines:
if re.match(r'^\-+$', line):
continue
if line in ['Parameters', 'Returns', 'Example', 'Examples', 'Attributes']:
if line in ['Parameters', 'Returns', 'Example', 'Examples', 'Attributes', 'Values']:
mode = line
continue
if line.strip() == '':
@@ -80,6 +81,19 @@ class DocInfo:
pass
elif mode == 'Example' or mode == 'Examples':
pass
elif mode == 'Values':
self.ProcessEnumValue(line)
elif mode == '':
self.description += line + '\n'
else:
raise Exception('Unknown mode = "{}"'.format(mode))
def ProcessEnumValue(self, line):
m = re.match(r'^\s*([A-Za-z][A-Za-z0-9_]+)\s*:\s*(.*)$', line)
if not m:
raise Exception('Invalid enum documentation: "{}"'.format(line))
pair = (m.group(1), m.group(2).strip())
self.enumValues.append(pair)
def ProcessParmAttrLine(self, line, item, itemlist):
if line.startswith(' '):
@@ -104,6 +118,15 @@ class DocInfo:
md += '\n'
return md
def EnumTable(self):
md = ''
if self.enumValues:
md += '| Value | Description |\n'
md += '| --- | --- |\n'
for (name, desc) in self.enumValues:
md += '| {} | {} |\n'.format('`' + name + '`', desc)
return md
def Markdown(self):
md = '\n'
if self.summary:
@@ -112,9 +135,17 @@ class DocInfo:
md += self.description + '\n\n'
md += self.Table(self.parameters, 'Parameter')
md += self.Table(self.attributes, 'Attribute')
md += self.EnumTable()
md += '\n'
return md
def VerifyEnum(self, members):
defs = set(name for (name, _) in self.enumValues)
if defs != members:
print('Actual enums: [' + ', '.join(members) + ']')
print('Documented enums: [' + ', '.join(defs) + ']')
raise Exception('Documented enums do not match actual enums.')
def MdSignature(sig):
text = str(sig)
text = HtmlEscape(text)
@@ -149,6 +180,21 @@ def MdClass(c):
md += '\n'
return md
def MdEnumType(c):
md = ''
doc = inspect.getdoc(c)
if doc:
md += '\n'
md += '---\n'
md += '\n'
md += '<a name="{}"></a>\n'.format(c.__name__)
md += '### ' + c.__name__ + '\n'
info = DocInfo(doc)
info.VerifyEnum(set(c.__members__))
md += info.Markdown()
md += '\n'
return md
def Markdown(module):
md = ''
funclist = []
@@ -179,14 +225,13 @@ def Markdown(module):
for c in classlist:
md += MdClass(c)
if False: # not yet ready to generate Markdown for enumerated types
md += '---\n'
md += '\n'
md += '<a name="enumerations"></a>\n'
md += '## Enumerated Types\n'
md += '\n'
for c in enumlist:
md += MdEnumType(c)
md += '---\n'
md += '\n'
md += '<a name="enumerations"></a>\n'
md += '## Enumerated Types\n'
md += '\n'
for c in enumlist:
md += MdEnumType(c)
if False: # not yet ready to generate Markdown for error types
md += '---\n'

113
source/python/README.md
View File

@@ -11,6 +11,12 @@
**Represents the geographic location of an observer on the surface of the Earth.**
| Type | Parameter | Description |
| --- | --- | --- |
| `float` | `latitude` | Geographic latitude in degrees north of the equator. |
| `float` | `longitude` | Geographic longitude in degrees east of the prime meridian at Greenwich, England. |
| `float` | `height` | Elevation above sea level in meters. |
@@ -21,6 +27,10 @@
**Represents a date and time used for performing astronomy calculations.**
All calculations performed by Astronomy Engine are based on
dates and times represented by `Time` objects.
| Type | Parameter | Description |
| --- | --- | --- |
| `float` | `ut` | UT1/UTC number of days since noon on January 1, 2000. See the `ut` attribute of this class for more details. |
@@ -32,6 +42,95 @@
---
<a name="enumerations"></a>
## Enumerated Types
---
<a name="ApsisKind"></a>
### ApsisKind
**Represents whether a satellite is at a closest or farthest point in its orbit.**
An apsis is a point in a satellite's orbit that is closest to,
or farthest from, the body it orbits (its primary).
`ApsisKind` is an enumerated type that indicates which of these
two cases applies to a particular apsis event.
| Value | Description |
| --- | --- |
| `Pericenter` | The satellite is at its closest point to its primary. |
| `Apocenter` | The satellite is at its farthest point from its primary. |
| `Invalid` | A placeholder for an undefined, unknown, or invalid apsis. |
---
<a name="Body"></a>
### Body
**The celestial bodies supported by Astronomy Engine calculations.**
| Value | Description |
| --- | --- |
| `Invalid` | An unknown, invalid, or undefined celestial body. |
| `Mercury` | The planet Mercury. |
| `Venus` | The planet Venus. |
| `Earth` | The planet Earth. |
| `Mars` | The planet Mars. |
| `Jupiter` | The planet Jupiter. |
| `Saturn` | The planet Saturn. |
| `Uranus` | The planet Uranus. |
| `Neptune` | The planet Neptune. |
| `Pluto` | The planet Pluto. |
| `Sun` | The Sun. |
| `Moon` | The Earth's moon. |
---
<a name="Direction"></a>
### Direction
**Indicates whether a body is rising above or setting below the horizon.**
Specifies the direction of a rising or setting event for a body.
For example, `Direction.Rise` is used to find sunrise times,
and `Direction.Set` is used to find sunset times.
| Value | Description |
| --- | --- |
| `Rise` | First appearance of a body as it rises above the horizon. |
| `Set` | Last appearance of a body as it sinks below the horizon. |
---
<a name="Refraction"></a>
### Refraction
**Selects if/how to correct for atmospheric refraction.**
Some functions allow enabling or disabling atmospheric refraction
for the calculated apparent position of a celestial body
as seen by an observer on the surface of the Earth.
| Value | Description |
| --- | --- |
| `Airless` | No atmospheric refraction correction. |
| `Normal` | Recommended correction for standard atmospheric refraction. |
| `JplHorizons` | Used only for compatibility testing with JPL Horizons online tool. |
---
<a name="functions"></a>
@@ -45,6 +144,10 @@
**Finds the Body enumeration value, given the name of a body.**
>>> astronomy.BodyCode('Mars')
<Body.Mars: 3>
| Type | Parameter | Description |
| --- | --- | --- |
| `str` | `name` | The common English name of a supported celestial body. |
@@ -59,6 +162,16 @@
**Calculates the geocentric position of the Moon at a given time.**
Given a time of observation, calculates the Moon's position as a vector.
The vector gives the location of the Moon's center relative to the Earth's center
with x-, y-, and z-components measured in astronomical units.
This algorithm is based on Nautical Almanac Office's *Improved Lunar Ephemeris* of 1954,
which in turn derives from E. W. Brown's lunar theories from the early twentieth century.
It is adapted from Turbo Pascal code from the book
[Astronomy on the Personal Computer](https://www.springer.com/us/book/9783540672210)
by Montenbruck and Pfleger.
| Type | Parameter | Description |
| --- | --- | --- |
| [`Time`](#Time) | `time` | The date and time for which to calculate the Moon's position. |

87
source/python/astronomy.py
View File

@@ -85,41 +85,35 @@ class Vector:
@enum.unique
class Body(enum.IntEnum):
"""The celestial bodies supported by Astronomy Engine calculations.
Values
------
Invalid: An unknown, invalid, or undefined celestial body.
Mercury: The planet Mercury.
Venus: The planet Venus.
Earth: The planet Earth.
Mars: The planet Mars.
Jupiter: The planet Jupiter.
Saturn: The planet Saturn.
Uranus: The planet Uranus.
Neptune: The planet Neptune.
Pluto: The planet Pluto.
Sun: The Sun.
Moon: The Earth's moon.
"""
Invalid = -1
"""A placeholder value for an unknown, undefined, or invalid body."""
Mercury = 0
"""The body code for the planet Mercury."""
Venus = 1
"""The body code for the planet Venus."""
Earth = 2
"""The body code for the planet Earth."""
Mars = 3
"""The body code for the planet Mars."""
Jupiter = 4
"""The body code for the planet Jupiter."""
Saturn = 5
"""The body code for the planet Saturn."""
Uranus = 6
"""The body code for the planet Uranus."""
Neptune = 7
"""The body code for the planet Neptune."""
Pluto = 8
"""The body code for the planet Pluto."""
Sun = 9
"""The body code for the Sun."""
Moon = 10
"""The body code for the Moon."""
def BodyCode(name):
"""Finds the Body enumeration value, given the name of a body.
@@ -434,9 +428,14 @@ class Time:
class Observer:
"""Represents the geographic location of an observer on the surface of the Earth.
:param latitude: Geographic latitude in degrees north of the equator.
:param longitude: Geographic longitude in degrees east of the prime meridian at Greenwich, England.
:param height: Elevation above sea level in meters.
Parameters
----------
latitude : float
Geographic latitude in degrees north of the equator.
longitude : float
Geographic longitude in degrees east of the prime meridian at Greenwich, England.
height : float
Elevation above sea level in meters.
"""
def __init__(self, latitude, longitude, height=0):
self.latitude = latitude
@@ -3079,6 +3078,18 @@ def Equator(body, time, observer, ofdate, aberration):
@enum.unique
class Refraction(enum.IntEnum):
"""Selects if/how to correct for atmospheric refraction.
Some functions allow enabling or disabling atmospheric refraction
for the calculated apparent position of a celestial body
as seen by an observer on the surface of the Earth.
Values
------
Airless: No atmospheric refraction correction.
Normal: Recommended correction for standard atmospheric refraction.
JplHorizons: Used only for compatibility testing with JPL Horizons online tool.
"""
Airless = 0
Normal = 1
JplHorizons = 2
@@ -3707,6 +3718,17 @@ def SearchHourAngle(body, observer, hourAngle, startTime):
@enum.unique
class Direction(enum.IntEnum):
"""Indicates whether a body is rising above or setting below the horizon.
Specifies the direction of a rising or setting event for a body.
For example, `Direction.Rise` is used to find sunrise times,
and `Direction.Set` is used to find sunset times.
Values
------
Rise: First appearance of a body as it rises above the horizon.
Set: Last appearance of a body as it sinks below the horizon.
"""
Rise = +1
Set = -1
@@ -3827,6 +3849,19 @@ def _distance_slope(direction, time):
@enum.unique
class ApsisKind(enum.IntEnum):
"""Represents whether a satellite is at a closest or farthest point in its orbit.
An apsis is a point in a satellite's orbit that is closest to,
or farthest from, the body it orbits (its primary).
`ApsisKind` is an enumerated type that indicates which of these
two cases applies to a particular apsis event.
Values
------
Pericenter: The satellite is at its closest point to its primary.
Apocenter: The satellite is at its farthest point from its primary.
Invalid: A placeholder for an undefined, unknown, or invalid apsis.
"""
Pericenter = 0
Apocenter = 1
Invalid = 2