From 8a18cdc58a725e05e6a775facaba5596e97f392e Mon Sep 17 00:00:00 2001 From: Don Cross Date: Sat, 13 Jul 2019 17:48:15 -0400 Subject: [PATCH] Python: include documentation about function return values in Markdown. --- generate/template/astronomy.py | 25 ++++++------ pydown/pydown.py | 14 ++++++- source/python/README.md | 70 ++++++++++++++++++++++++++++++++++ source/python/astronomy.py | 25 ++++++------ 4 files changed, 109 insertions(+), 25 deletions(-) diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 2cc7c6a9..7217a1bf 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -143,7 +143,7 @@ def BodyCode(name): Returns ------- - Body + #Body If `name` is a valid body name, returns the enumeration value associated with that body. Otherwise, returns `Body.Invalid`. @@ -341,6 +341,7 @@ class Time: Returns ------- + #Time """ micro = round(math.fmod(second, 1.0) * 1000000) second = math.floor(second - micro/1000000) @@ -772,7 +773,7 @@ def GeoMoon(time): Returns ------- - Vector + #Vector The Moon's position as a vector in J2000 Cartesian equatorial coordinates. """ @@ -1146,7 +1147,7 @@ def GeoVector(body, time, aberration): Returns ------- - Vector + #Vector A geocentric position vector of the center of the given body. """ if body == Body.Moon: @@ -1228,7 +1229,7 @@ def Equator(body, time, observer, ofdate, aberration): Returns ------- - Equatorial + #EquatorialCoordinates Equatorial coordinates in the specified frame of reference. """ gc_observer = _geo_pos(time, observer) @@ -1316,7 +1317,7 @@ def Horizon(time, observer, ra, dec, refraction): Returns ------- - HorizontalCoordinates + #HorizontalCoordinates The horizontal coordinates (altitude and azimuth), along with equatorial coordinates (right ascension and declination), all optionally corrected for atmospheric refraction. See remarks above @@ -1481,7 +1482,7 @@ def SunPosition(time): Returns ------- - EclipticCoordinates + #EclipticCoordinates The ecliptic coordinates of the Sun using the Earth's true equator of date. """ # Correct for light travel time from the Sun. @@ -1510,7 +1511,7 @@ def Ecliptic(equ): Returns ------- - EclipticCoordinates + #EclipticCoordinates Ecliptic coordinates in the J2000 frame of reference. """ # Based on NOVAS functions equ2ecl() and equ2ecl_vec(). @@ -1535,7 +1536,7 @@ def EclipticLongitude(body, time): Returns ------- - float + `float` An angular value in degrees indicating the ecliptic longitude of the body. """ if body == Body.Sun: @@ -1561,7 +1562,7 @@ def AngleFromSun(body, time): Returns ------- - float + `float` A numeric value indicating the angle in degrees between the Sun and the specified body as seen from the center of the Earth. """ @@ -1605,7 +1606,7 @@ def LongitudeFromSun(body, time): Returns ------- - float + `float` An angle in degrees in the range [0, 360). """ if body == Body.Earth: @@ -1680,7 +1681,7 @@ def Elongation(body, time): Returns ------- - ElongationEvent + #ElongationEvent """ angle = LongitudeFromSun(body, time) if angle > 180.0: @@ -1746,7 +1747,7 @@ def SearchRelativeLongitude(body, targetRelLon, startTime): Returns ------- - Time + #Time The date and time of the relative longitude event. """ if body == Body.Earth: diff --git a/pydown/pydown.py b/pydown/pydown.py index 8aee94d9..012bfed1 100755 --- a/pydown/pydown.py +++ b/pydown/pydown.py @@ -51,6 +51,8 @@ class DocInfo: self.parameters = [] self.attributes = [] self.enumValues = [] + self.returnType = None + self.returns = '' lines = doc.split('\n') @@ -80,7 +82,10 @@ class DocInfo: elif mode == 'Attributes': currentAttr = self.ProcessParmAttrLine(line, currentAttr, self.attributes) elif mode == 'Returns': - pass + if line.startswith(' '): + self.returns += line.strip() + '\n' + else: + self.returnType = line.strip() elif mode == 'Example' or mode == 'Examples': pass elif mode == 'Values': @@ -145,6 +150,13 @@ class DocInfo: md += self.Table(self.parameters, 'Parameter') md += self.Table(self.attributes, 'Attribute') md += self.EnumTable() + if self.returns or self.returnType: + md += '### Returns' + if self.returnType: + md += ': ' + self.returnType + md += '\n' + md += self.returns + '\n' + md += '\n' md += '\n' return md diff --git a/source/python/README.md b/source/python/README.md index 13dcdaa7..b535b7c5 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -146,6 +146,9 @@ dates and times represented by `Time` objects. | `int` | `minute` | The UTC minute, in the range 0..59. | | `float` | `second` | The real-valued UTC second, in the range [0, 60). | +### Returns: #Time + + @@ -392,6 +395,11 @@ easy it is to see the body away from the glare of the Sun. | [`Body`](#Body) | `body` | The celestial body whose angle from the Sun is to be measured. Not allowed to be `Body.Earth`. | | [`Time`](#Time) | `time` | The time at which the observation is made. | +### Returns: `float` +A numeric value indicating the angle in degrees between the Sun +and the specified body as seen from the center of the Earth. + + @@ -412,6 +420,12 @@ easy it is to see the body away from the glare of the Sun. | --- | --- | --- | | `str` | `name` | The common English name of a supported celestial body. | +### Returns: #Body +If `name` is a valid body name, returns the enumeration +value associated with that body. +Otherwise, returns `Body.Invalid`. + + @@ -429,6 +443,10 @@ equ : EquatorialCoordinates Equatorial coordinates in the J2000 frame of reference. +### Returns: #EclipticCoordinates +Ecliptic coordinates in the J2000 frame of reference. + + @@ -451,6 +469,10 @@ time : Time | --- | --- | --- | | [`Body`](#Body) | `body` | A body other than the Sun. | +### Returns: `float` +An angular value in degrees indicating the ecliptic longitude of the body. + + @@ -482,6 +504,9 @@ time : Time | --- | --- | --- | | [`Body`](#Body) | `body` | The celestial body whose visibility is to be calculated. | +### Returns: #ElongationEvent + + @@ -512,6 +537,10 @@ Correction for aberration is optional, using the `aberration` parameter. | `bool` | `ofdate` | Selects the date of the Earth's equator in which to express the equatorial coordinates. If `True`, returns coordinates using the equator and equinox of date. If `False`, returns coordinates converted to the J2000 system. | | `bool` | `aberration` | If `True`, corrects for aberration of light based on the motion of the Earth with respect to the heliocentric origin. If `False`, does not correct for aberration. | +### Returns: #EquatorialCoordinates +Equatorial coordinates in the specified frame of reference. + + @@ -536,6 +565,10 @@ by Montenbruck and Pfleger. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate the Moon's position. | +### Returns: #Vector +The Moon's position as a vector in J2000 Cartesian equatorial coordinates. + + @@ -567,6 +600,10 @@ movement of the Earth with respect to the rays of light coming from that body. | [`Time`](#Time) | `time` | The date and time for which to calculate the position. | | `bool` | `aberration` | A boolean value indicating whether to correct for aberration. | +### Returns: #Vector +A geocentric position vector of the center of the given body. + + @@ -592,6 +629,11 @@ the year range 1700..2200, this function raise an exception. | [`Body`](#Body) | `body` | The celestial body whose heliocentric position is to be calculated: The Sun, Moon, or any of the planets. | | [`Time`](#Time) | `time` | The time at which to calculate the heliocentric position. | +### Returns: #Vector +A heliocentric position vector of the center of the given body +at the given time. + + @@ -624,6 +666,13 @@ the right ascension and declination in the returned object will be numerically i to the respective `ra` and `dec` values passed in. +### Returns: #HorizontalCoordinates +The horizontal coordinates (altitude and azimuth), along with +equatorial coordinates (right ascension and declination), all +optionally corrected for atmospheric refraction. See remarks above +for more details. + + @@ -658,6 +707,10 @@ time : Time | --- | --- | --- | | [`Body`](#Body) | `body` | The celestial body for which to find longitude from the Sun. | +### Returns: `float` +An angle in degrees in the range [0, 360). + + @@ -719,6 +772,15 @@ dt_tolerance_seconds : float | --- | --- | --- | | `function(context, Time)` | `func` | A function that takes an arbitrary context parameter and a #Time parameter. Returns a float value. See remarks above for more details. | +### Returns: #Time or `None` +If the search is successful, returns a #Time object that is within +`dt_tolerance_seconds` of an ascending root. +In this case, the returned time value will always be within the +inclusive range [`t1`, `t2`]. +If there is no ascending root, or there is more than one ascending root, +the function returns `None`. + + @@ -764,6 +826,10 @@ the Earth and another planet: | `float` | `targetRelLon` | The desired relative longitude, expressed in degrees. Must be in the range [0, 360). | | [`Time`](#Time) | `startTime` | The date and time at which to begin the search. | +### Returns: #Time +The date and time of the relative longitude event. + + @@ -792,5 +858,9 @@ In fact, the function #Seasons does use this function for that purpose. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate the Sun's position. | +### Returns: #EclipticCoordinates +The ecliptic coordinates of the Sun using the Earth's true equator of date. + + diff --git a/source/python/astronomy.py b/source/python/astronomy.py index 96517bd8..c6d92c99 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -143,7 +143,7 @@ def BodyCode(name): Returns ------- - Body + #Body If `name` is a valid body name, returns the enumeration value associated with that body. Otherwise, returns `Body.Invalid`. @@ -432,6 +432,7 @@ class Time: Returns ------- + #Time """ micro = round(math.fmod(second, 1.0) * 1000000) second = math.floor(second - micro/1000000) @@ -2086,7 +2087,7 @@ def GeoMoon(time): Returns ------- - Vector + #Vector The Moon's position as a vector in J2000 Cartesian equatorial coordinates. """ @@ -3207,7 +3208,7 @@ def GeoVector(body, time, aberration): Returns ------- - Vector + #Vector A geocentric position vector of the center of the given body. """ if body == Body.Moon: @@ -3289,7 +3290,7 @@ def Equator(body, time, observer, ofdate, aberration): Returns ------- - Equatorial + #EquatorialCoordinates Equatorial coordinates in the specified frame of reference. """ gc_observer = _geo_pos(time, observer) @@ -3377,7 +3378,7 @@ def Horizon(time, observer, ra, dec, refraction): Returns ------- - HorizontalCoordinates + #HorizontalCoordinates The horizontal coordinates (altitude and azimuth), along with equatorial coordinates (right ascension and declination), all optionally corrected for atmospheric refraction. See remarks above @@ -3542,7 +3543,7 @@ def SunPosition(time): Returns ------- - EclipticCoordinates + #EclipticCoordinates The ecliptic coordinates of the Sun using the Earth's true equator of date. """ # Correct for light travel time from the Sun. @@ -3571,7 +3572,7 @@ def Ecliptic(equ): Returns ------- - EclipticCoordinates + #EclipticCoordinates Ecliptic coordinates in the J2000 frame of reference. """ # Based on NOVAS functions equ2ecl() and equ2ecl_vec(). @@ -3596,7 +3597,7 @@ def EclipticLongitude(body, time): Returns ------- - float + `float` An angular value in degrees indicating the ecliptic longitude of the body. """ if body == Body.Sun: @@ -3622,7 +3623,7 @@ def AngleFromSun(body, time): Returns ------- - float + `float` A numeric value indicating the angle in degrees between the Sun and the specified body as seen from the center of the Earth. """ @@ -3666,7 +3667,7 @@ def LongitudeFromSun(body, time): Returns ------- - float + `float` An angle in degrees in the range [0, 360). """ if body == Body.Earth: @@ -3741,7 +3742,7 @@ def Elongation(body, time): Returns ------- - ElongationEvent + #ElongationEvent """ angle = LongitudeFromSun(body, time) if angle > 180.0: @@ -3807,7 +3808,7 @@ def SearchRelativeLongitude(body, targetRelLon, startTime): Returns ------- - Time + #Time The date and time of the relative longitude event. """ if body == Body.Earth: