From 7040ff8684f2cda71333529912d0a9d6aef84e2c Mon Sep 17 00:00:00 2001 From: Don Cross Date: Wed, 18 Dec 2019 16:53:13 -0500 Subject: [PATCH] Cleaned up documented return types for Python functions. Never use pound-signs inside documentation for Python return types. Automatically create internal link just like for function parameter types. Added special case logic in pydown.py for "Time or `None`". Fixed minor documentation mistakes in JS version. --- generate/template/astronomy.js | 4 +- generate/template/astronomy.py | 63 +++++++++++----------- pydown/pydown.py | 6 ++- source/js/README.md | 4 +- source/js/astronomy.js | 4 +- source/python/README.md | 96 +++++++++++++++++----------------- source/python/astronomy.py | 63 +++++++++++----------- 7 files changed, 123 insertions(+), 117 deletions(-) diff --git a/generate/template/astronomy.js b/generate/template/astronomy.js index bead1437..8aba9335 100644 --- a/generate/template/astronomy.js +++ b/generate/template/astronomy.js @@ -3684,7 +3684,7 @@ Astronomy.Rotation_EQD_HOR = function(time, observer) { * This is one of the family of functions that returns a rotation matrix * for converting from one orientation to another. * Source: HOR = horizontal system (x=North, y=West, z=Zenith). - * Source: EQD = equatorial system, using equator of the specified date/time. + * Target: EQD = equatorial system, using equator of the specified date/time. * * @param {Astronomy.AstroTime} time * The date and time at which the Earth's equator applies. @@ -3707,7 +3707,7 @@ Astronomy.Rotation_HOR_EQD = function(time, observer) { * This is one of the family of functions that returns a rotation matrix * for converting from one orientation to another. * Source: HOR = horizontal system (x=North, y=West, z=Zenith). - * Source: EQJ = equatorial system, using equator at the J2000 epoch. + * Target: EQJ = equatorial system, using equator at the J2000 epoch. * * @param {Astronomy.AstroTime} time * The date and time of the observation. diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index f6fb8f0e..32bfbb12 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,7 +341,7 @@ class Time: Returns ------- - #Time + Time """ micro = round(math.fmod(second, 1.0) * 1000000) second = math.floor(second - micro/1000000) @@ -360,7 +360,7 @@ class Time: Returns ------- - #Time + Time """ ut = (datetime.datetime.utcnow() - _EPOCH).total_seconds() / 86400.0 return Time(ut) @@ -388,7 +388,7 @@ class Time: Returns ------- - #Time + Time """ return Time(self.ut + days) @@ -405,7 +405,7 @@ class Time: Returns ------- - `datetime` + datetime """ return _EPOCH + datetime.timedelta(days=self.ut) @@ -862,7 +862,7 @@ def GeoMoon(time): Returns ------- - #Vector + Vector The Moon's position as a vector in J2000 Cartesian equatorial coordinates. """ @@ -1077,7 +1077,7 @@ def Search(func, context, t1, t2, dt_tolerance_seconds): Returns ------- - #Time or `None` + 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 @@ -1184,7 +1184,7 @@ def HelioVector(body, time): Returns ------- - #Vector + Vector A heliocentric position vector of the center of the given body at the given time. """ @@ -1236,7 +1236,7 @@ def GeoVector(body, time, aberration): Returns ------- - #Vector + Vector A geocentric position vector of the center of the given body. """ if body == Body.Moon: @@ -1318,7 +1318,7 @@ def Equator(body, time, observer, ofdate, aberration): Returns ------- - #EquatorialCoordinates + EquatorialCoordinates Equatorial coordinates in the specified frame of reference. """ gc_observer = _geo_pos(time, observer) @@ -1427,7 +1427,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 @@ -1659,7 +1659,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. @@ -1690,7 +1690,7 @@ def Ecliptic(equ): Returns ------- - #EclipticCoordinates + EclipticCoordinates Ecliptic coordinates in the J2000 frame of reference. """ # Based on NOVAS functions equ2ecl() and equ2ecl_vec(). @@ -1715,7 +1715,7 @@ def EclipticLongitude(body, time): Returns ------- - `float` + float An angular value in degrees indicating the ecliptic longitude of the body. """ if body == Body.Sun: @@ -1741,7 +1741,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. """ @@ -1785,7 +1785,7 @@ def LongitudeFromSun(body, time): Returns ------- - `float` + float An angle in degrees in the range [0, 360). """ if body == Body.Earth: @@ -1860,7 +1860,7 @@ def Elongation(body, time): Returns ------- - #ElongationEvent + ElongationEvent """ angle = LongitudeFromSun(body, time) if angle > 180.0: @@ -1926,7 +1926,7 @@ def SearchRelativeLongitude(body, targetRelLon, startTime): Returns ------- - #Time + Time The date and time of the relative longitude event. """ if body == Body.Earth: @@ -1995,7 +1995,7 @@ def SearchMaxElongation(body, startTime): Returns ------- - #ElongationEvent + ElongationEvent """ if body == Body.Mercury: s1 = 50.0 @@ -2115,7 +2115,7 @@ def SearchSunLongitude(targetLon, startTime, limitDays): Returns ------- - #Time or `None` + Time or `None` """ t2 = startTime.AddDays(limitDays) return Search(_sun_offset, targetLon, startTime, t2, 1.0) @@ -2139,7 +2139,7 @@ def MoonPhase(time): Returns ------- - `float` + float """ return LongitudeFromSun(Body.Moon, time) @@ -2176,7 +2176,7 @@ def SearchMoonPhase(targetLon, startTime, limitDays): Returns ------- - #Time or `None` + Time or `None` """ # To avoid discontinuities in the _moon_offset function causing problems, # we need to approximate when that function will next return 0. @@ -2240,7 +2240,7 @@ def SearchMoonQuarter(startTime): Returns ------- - #MoonQuarter + MoonQuarter """ angle = MoonPhase(startTime) quarter = int(1 + math.floor(angle / 90.0)) % 4 @@ -2265,7 +2265,7 @@ def NextMoonQuarter(mq): Returns ------- - #MoonQuarter + MoonQuarter """ # Skip 6 days past the previous found moon quarter to find the next one. # This is less than the minimum possible increment. @@ -2406,7 +2406,7 @@ def Illumination(body, time): Returns ------- - #IlluminationInfo + IlluminationInfo """ if body == Body.Earth: raise EarthNotAllowedError() @@ -2476,7 +2476,7 @@ def SearchPeakMagnitude(body, startTime): Returns ------- - #IlluminationInfo + IlluminationInfo """ # s1 and s2 are relative longitudes within which peak magnitude of Venus can occur. s1 = 10.0 @@ -2612,7 +2612,7 @@ def SearchHourAngle(body, observer, hourAngle, startTime): Returns ------- - #HourAngleEvent + HourAngleEvent """ if body == Body.Earth: raise EarthNotAllowedError() @@ -2732,7 +2732,7 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): Returns ------- - #Time or `None` + Time or `None` If the rise or set time is found within the specified time window, this function returns that time. Otherwise, it returns `None`. """ @@ -2857,7 +2857,7 @@ def Seasons(year): Returns ------- - #SeasonInfo + SeasonInfo """ mar_equinox = _FindSeasonChange(0, year, 3, 19) jun_solstice = _FindSeasonChange(90, year, 6, 19) @@ -2951,7 +2951,7 @@ def SearchLunarApsis(startTime): Returns ------- - #Apsis + Apsis """ increment = 5.0 # number of days to skip on each iteration t1 = startTime @@ -3010,7 +3010,7 @@ def NextLunarApsis(apsis): Returns ------- - #Apsis + Apsis """ skip = 11.0 # number of days to skip to start looking for next apsis event time = apsis.time.AddDays(skip) @@ -3516,6 +3516,7 @@ def Rotation_EQD_ECL(time): Returns ------- + RotationMatrix A rotation matrix that converts EQD to ECL. """ eqd_eqj = Rotation_EQD_EQJ(time) diff --git a/pydown/pydown.py b/pydown/pydown.py index aeda883d..ca6d91e9 100755 --- a/pydown/pydown.py +++ b/pydown/pydown.py @@ -34,6 +34,10 @@ def HtmlEscape(text): return text def SymbolLink(name): + # Special case: Search and related functions have return type = "Time or `None`" + m = re.match(r'^\s*([a-zA-Z0-9_]+)\s+or\s+`None`\s*$', name) + if m: + return SymbolLink(m.group(1)) + ' or `None`' if 'a' <= name[0] <= 'z': # Assume built-in Python identifier, so do not link return '`{0}`'.format(name) @@ -159,7 +163,7 @@ class DocInfo: if self.returns or self.returnType: md += '### Returns' if self.returnType: - md += ': ' + self.returnType + md += ': ' + SymbolLink(self.returnType) md += '\n' md += self.returns + '\n' md += '\n' diff --git a/source/js/README.md b/source/js/README.md index 5023800b..8eb79339 100644 --- a/source/js/README.md +++ b/source/js/README.md @@ -1467,7 +1467,7 @@ Calculates a rotation matrix from horizontal (HOR) to equatorial of-date (EQD). This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: HOR = horizontal system (x=North, y=West, z=Zenith). -Source: EQD = equatorial system, using equator of the specified date/time. +Target: EQD = equatorial system, using equator of the specified date/time. **Kind**: static method of [Astronomy](#Astronomy) **Returns**: [RotationMatrix](#Astronomy.RotationMatrix) - A rotation matrix that converts HOR to EQD at `time` and for `observer`. @@ -1488,7 +1488,7 @@ Calculates a rotation matrix from horizontal (HOR) to J2000 equatorial (EQJ). This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: HOR = horizontal system (x=North, y=West, z=Zenith). -Source: EQJ = equatorial system, using equator at the J2000 epoch. +Target: EQJ = equatorial system, using equator at the J2000 epoch. **Kind**: static method of [Astronomy](#Astronomy) **Returns**: [RotationMatrix](#Astronomy.RotationMatrix) - A rotation matrix that converts HOR to EQD at time and for observer. diff --git a/source/js/astronomy.js b/source/js/astronomy.js index 2d9ff213..2b39fb3c 100644 --- a/source/js/astronomy.js +++ b/source/js/astronomy.js @@ -4705,7 +4705,7 @@ Astronomy.Rotation_EQD_HOR = function(time, observer) { * This is one of the family of functions that returns a rotation matrix * for converting from one orientation to another. * Source: HOR = horizontal system (x=North, y=West, z=Zenith). - * Source: EQD = equatorial system, using equator of the specified date/time. + * Target: EQD = equatorial system, using equator of the specified date/time. * * @param {Astronomy.AstroTime} time * The date and time at which the Earth's equator applies. @@ -4728,7 +4728,7 @@ Astronomy.Rotation_HOR_EQD = function(time, observer) { * This is one of the family of functions that returns a rotation matrix * for converting from one orientation to another. * Source: HOR = horizontal system (x=North, y=West, z=Zenith). - * Source: EQJ = equatorial system, using equator at the J2000 epoch. + * Target: EQJ = equatorial system, using equator at the J2000 epoch. * * @param {Astronomy.AstroTime} time * The date and time of the observation. diff --git a/source/python/README.md b/source/python/README.md index c61b533c..39ebf9c7 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -246,7 +246,7 @@ The value of the calling object is not modified. This function creates a brand n | --- | --- | --- | | `float` | `days` | A floating point number of days by which to adjust `time`. May be negative, 0, or positive. | -### Returns: #Time +### Returns: [`Time`](#Time) ### Time.Make(year, month, day, hour, minute, second) @@ -262,7 +262,7 @@ The value of the calling object is not modified. This function creates a brand n | `int` | `minute` | The UTC minute, in the range 0..59. | | `float` | `second` | The real-valued UTC second, in the range [0, 60). | -### Returns: #Time +### Returns: [`Time`](#Time) ### Time.Now() @@ -274,7 +274,7 @@ Converts that date and time to a #Time value and returns the result. Callers can pass this value to other Astronomy Engine functions to calculate current observational conditions. -### Returns: #Time +### Returns: [`Time`](#Time) ### Time.Utc(self) @@ -503,7 +503,7 @@ and the specified body as seen from the center of the Earth. | --- | --- | --- | | `str` | `name` | The common English name of a supported celestial body. | -### Returns: #Body +### Returns: [`Body`](#Body) If `name` is a valid body name, returns the enumeration value associated with that body. Otherwise, returns `Body.Invalid`. @@ -524,7 +524,7 @@ b : RotationMatrix | --- | --- | --- | | [`RotationMatrix`](#RotationMatrix) | `a` | The first rotation to apply. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) The combined rotation matrix. --- @@ -542,7 +542,7 @@ which are relative to the plane of the Earth's orbit around the Sun. | --- | --- | --- | | [`EquatorialCoordinates`](#EquatorialCoordinates) | `equ` | Equatorial coordinates in the J2000 frame of reference. | -### Returns: #EclipticCoordinates +### Returns: [`EclipticCoordinates`](#EclipticCoordinates) Ecliptic coordinates in the J2000 frame of reference. --- @@ -593,7 +593,7 @@ time : Time | --- | --- | --- | | [`Body`](#Body) | `body` | The celestial body whose visibility is to be calculated. | -### Returns: #ElongationEvent +### Returns: [`ElongationEvent`](#ElongationEvent) --- @@ -621,7 +621,7 @@ 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 +### Returns: [`EquatorialCoordinates`](#EquatorialCoordinates) Equatorial coordinates in the specified frame of reference. --- @@ -635,7 +635,7 @@ Equatorial coordinates in the specified frame of reference. | --- | --- | --- | | [`Vector`](#Vector) | `vec` | A vector in an equatorial coordinate system. | -### Returns: Equatorial +### Returns: [`Equatorial`](#Equatorial) Angular coordinates expressed in the same equatorial system as `vec`. --- @@ -658,7 +658,7 @@ by Montenbruck and Pfleger. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time for which to calculate the Moon's position. | -### Returns: #Vector +### Returns: [`Vector`](#Vector) The Moon's position as a vector in J2000 Cartesian equatorial coordinates. --- @@ -688,7 +688,7 @@ 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 +### Returns: [`Vector`](#Vector) A geocentric position vector of the center of the given body. --- @@ -712,7 +712,7 @@ 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 +### Returns: [`Vector`](#Vector) A heliocentric position vector of the center of the given body at the given time. @@ -752,7 +752,7 @@ to the respective `ra` and `dec` values passed in. | `float` | `dec` | Declination in degrees of the celestial object, referred to the mean equator of date for the J2000 epoch. Positive values are north of the celestial equator and negative values are south of it. | | [`Refraction`](#Refraction) | `refraction` | The option for selecting whether to correct for atmospheric lensing. If `Refraction.Normal`, a well-behaved refraction model is used. If `Refraction.None`, no refraction correct is performed. `Refraction.JplHorizons` is used only for compatibility testing with the JPL Horizons online tool. | -### Returns: #HorizontalCoordinates +### 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 @@ -812,7 +812,7 @@ the rings appear edge-on, and are thus nearly invisible from the Earth. The `rin | [`Body`](#Body) | `body` | The Sun, Moon, or any planet other than the Earth. | | [`Time`](#Time) | `time` | The date and time of the observation. | -### Returns: #IlluminationInfo +### Returns: [`IlluminationInfo`](#IlluminationInfo) --- @@ -832,7 +832,7 @@ but refraction first must be removed from the observed position. | [`Refraction`](#Refraction) | `refraction` | `Refraction.Normal` - corrects for atmospheric refraction (recommended). `Refraction.Airless` - no correction is performed. `Refraction.JplHorizons` - For JPL Horizons compatibility testing only. | | `float` | `bent_altitude` | The apparent altitude that includes atmospheric refraction. | -### Returns: float +### Returns: `float` The angular adjustment in degrees, to be added to the altitude angle to correct for atmospheric lensing. This will be less than or equal to zero. @@ -851,7 +851,7 @@ this function returns the matrix that reverses that trasnform. | --- | --- | --- | | [`RotationMatrix`](#RotationMatrix) | `rotation` | The rotation matrix to be inverted. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) The inverse rotation matrix. --- @@ -925,7 +925,7 @@ See #SearchLunarApsis for more details. | --- | --- | --- | | [`Apsis`](#Apsis) | `apsis` | | -### Returns: #Apsis +### Returns: [`Apsis`](#Apsis) --- @@ -943,7 +943,7 @@ the one passed in as the parameter `mq`. | --- | --- | --- | | [`MoonQuarter`](#MoonQuarter) | `mq` | A value returned by a prior call to #SearchMoonQuarter or #NextMoonQuarter. | -### Returns: #MoonQuarter +### Returns: [`MoonQuarter`](#MoonQuarter) --- @@ -962,7 +962,7 @@ due to lensing of the Earth's atmosphere. | [`Refraction`](#Refraction) | `refraction` | The option for selecting whether to correct for atmospheric lensing. If `Refraction.Normal`, a well-behaved refraction model is used. If `Refraction.Airless`, no refraction correct is performed. `Refraction.JplHorizons` is used only for compatibility testing with the JPL Horizons online tool. | | `float` | `altitude` | The number of degrees above (positive) or below (negative) the horizon an object is, before being corrected for refraction. | -### Returns: float +### Returns: `float` The number of additional degrees of altitude an object appears to have, due to atmospheric refraction, depending on the option selected by the `refraction` parameter. @@ -982,7 +982,7 @@ in another orientation. | [`RotationMatrix`](#RotationMatrix) | `rotation` | A rotation matrix that specifies how the orientation of the vector is to be changed. | | [`Vector`](#Vector) | `vector` | The vector whose orientation is to be changed. | -### Returns: Vector +### Returns: [`Vector`](#Vector) A vector in the orientation specified by `rotation`. --- @@ -1001,7 +1001,7 @@ Target: EQD = equatorial system, using equator of date. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time of the desired equator. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts ECL to EQD. --- @@ -1016,7 +1016,7 @@ for converting from one orientation to another. Source: ECL = ecliptic system, using equator at J2000 epoch. Target: EQJ = equatorial system, using equator at J2000 epoch. -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts ECL to EQJ. --- @@ -1038,7 +1038,7 @@ to a traditional altitude/azimuth pair. | [`Time`](#Time) | `time` | The date and time of the desired horizontal orientation. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that defines the observer's horizon. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts ECL to HOR at `time` and for `observer`. The components of the horizontal vector are: x = north, y = west, z = zenith (straight up from the observer). @@ -1061,7 +1061,7 @@ Target: ECL = ecliptic system, using equator at J2000 epoch. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time of the source equator. | -### Returns +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQD to ECL. --- @@ -1080,7 +1080,7 @@ Target: EQJ = equatorial system, using equator at J2000 epoch. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time at which the Earth's equator defines the source orientation. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQD at `time` to EQJ. --- @@ -1102,7 +1102,7 @@ to a traditional altitude/azimuth pair. | [`Time`](#Time) | `time` | The date and time at which the Earth's equator applies. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that defines the observer's location. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQD to HOR at `time` and for `observer`. The components of the horizontal vector are: x = north, y = west, z = zenith (straight up from the observer). @@ -1121,7 +1121,7 @@ for converting from one orientation to another. Source: EQJ = equatorial system, using equator at J2000 epoch. Target: ECL = ecliptic system, using equator at J2000 epoch. -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQJ to ECL. --- @@ -1140,7 +1140,7 @@ Target: EQD = equatorial system, using equator of the specified date/time. | --- | --- | --- | | [`Time`](#Time) | `time` | The date and time at which the Earth's equator defines the target orientation. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQJ to EQD at `time`. --- @@ -1162,7 +1162,7 @@ a traditional altitude/azimuth pair. | [`Time`](#Time) | `time` | The date and time of the desired horizontal orientation. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that defines the observer's horizon. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts EQJ to HOR at `time` and for `observer`. The components of the horizontal vector are: x = north, y = west, z = zenith (straight up from the observer). @@ -1186,7 +1186,7 @@ Target: ECL = ecliptic system, using equator at J2000 epoch. | [`Time`](#Time) | `time` | The date and time of the horizontal observation. | | [`Observer`](#Observer) | `observer` | The location of the horizontal observer. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts HOR to ECL. --- @@ -1206,7 +1206,7 @@ Target: EQD = equatorial system, using equator of the specified date/time. | [`Time`](#Time) | `time` | The date and time at which the Earth's equator applies. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that defines the observer's horizon. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts HOR to EQD at `time` and for `observer`. --- @@ -1226,7 +1226,7 @@ Target: EQJ = equatorial system, using equator at the J2000 epoch. | [`Time`](#Time) | `time` | The date and time of the observation. | | [`Observer`](#Observer) | `observer` | A location near the Earth's mean sea level that define's the observer's horizon. | -### Returns: RotationMatrix +### Returns: [`RotationMatrix`](#RotationMatrix) A rotation matrix that converts HOR to EQD at `time` and for `observer`. --- @@ -1286,7 +1286,7 @@ 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` +### Returns: [`Time`](#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 @@ -1326,7 +1326,7 @@ of the body at that time, as seen by the given observer. | `float` | `hourAngle` | An hour angle value in the range [0.0, 24.0) indicating the number of sidereal hours after the body's most recent culmination. | | [`Time`](#Time) | `startTime` | The date and time at which to start the search. | -### Returns: #HourAngleEvent +### Returns: [`HourAngleEvent`](#HourAngleEvent) --- @@ -1351,7 +1351,7 @@ another call of `NextLunarApsis` as many times as desired. | --- | --- | --- | | [`Time`](#Time) | `startTime` | The date and time at which to start searching for the next perigee or apogee. | -### Returns: #Apsis +### Returns: [`Apsis`](#Apsis) --- @@ -1374,7 +1374,7 @@ observed in the morning or evening. See #ElongationEvent for more details about | [`Body`](#Body) | `body` | Either `Body.Mercury` or `Body.Venus`. Any other value will result in an exception. To find the best viewing opportunities for planets farther from the Sun than the Earth is (Mars through Pluto), use #SearchRelativeLongitude to find the next opposition event. | | [`Time`](#Time) | `startTime` | The date and time at which to begin the search. The maximum elongation event found will always be the first one that occurs after this date and time. | -### Returns: #ElongationEvent +### Returns: [`ElongationEvent`](#ElongationEvent) --- @@ -1399,7 +1399,7 @@ This function is useful for finding general phase angles outside those four quar | [`Time`](#Time) | `startTime` | The beginning of the time window in which to search for the Moon reaching the specified phase. | | `float` | `limitDays` | The number of days after `startTime` that limits the time window for the search. | -### Returns: #Time or `None` +### Returns: [`Time`](#Time) or `None` --- @@ -1419,7 +1419,7 @@ followed by calls to #NextMoonQuarter as many times as desired. | --- | --- | --- | | [`Time`](#Time) | `startTime` | The date and time at which to start the search. | -### Returns: #MoonQuarter +### Returns: [`MoonQuarter`](#MoonQuarter) --- @@ -1444,7 +1444,7 @@ However, the difference is minor and has little practical value. | [`Body`](#Body) | `body` | Currently only `Body.Venus` is allowed. Any other value results in an exception. See remarks above for more details. | | [`Time`](#Time) | `startTime` | The date and time to start searching for the next peak magnitude event. | -### Returns: #IlluminationInfo +### Returns: [`IlluminationInfo`](#IlluminationInfo) --- @@ -1487,7 +1487,7 @@ 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 +### Returns: [`Time`](#Time) The date and time of the relative longitude event. --- @@ -1520,7 +1520,7 @@ Therefore callers must not assume that the function will always succeed. | [`Time`](#Time) | `startTime` | The date and time at which to start the search. | | `float` | `limitDays` | Limits how many days to search for a rise or set time. To limit a rise or set time to the same day, you can use a value of 1 day. In cases where you want to find the next rise or set time no matter how far in the future (for example, for an observer near the south pole), you can pass in a larger value like 365. | -### Returns: #Time or `None` +### Returns: [`Time`](#Time) or `None` If the rise or set time is found within the specified time window, this function returns that time. Otherwise, it returns `None`. @@ -1553,7 +1553,7 @@ limitDays : float It is recommended to keep this value between 1 and 10 days. See remarks above for more details. -### Returns: #Time or `None` +### Returns: [`Time`](#Time) or `None` --- @@ -1584,7 +1584,7 @@ of winter in the southern hemisphere. | --- | --- | --- | | `int` | `year` | The calendar year number for which to calculate equinoxes and solstices. The value may be any integer, but only the years 1800 through 2100 have been validated for accuracy: unit testing against data from the United States Naval Observatory confirms that all equinoxes and solstices for that range of years are within 2 minutes of the correct time. | -### Returns: #SeasonInfo +### Returns: [`SeasonInfo`](#SeasonInfo) --- @@ -1599,7 +1599,7 @@ Given a Cartesian vector, returns latitude, longitude, and distance. | --- | --- | --- | | [`Vector`](#Vector) | `vector` | Cartesian vector to be converted to spherical coordinates. | -### Returns: Spherical +### Returns: [`Spherical`](#Spherical) Spherical coordinates that are equivalent to the given vector. --- @@ -1626,7 +1626,7 @@ 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 +### Returns: [`EclipticCoordinates`](#EclipticCoordinates) The ecliptic coordinates of the Sun using the Earth's true equator of date. --- @@ -1641,7 +1641,7 @@ The ecliptic coordinates of the Sun using the Earth's true equator of date. | [`Equatorial`](#Equatorial) | `equ` | Angular equatorial coordinates to be converted to a vector. | | [`Time`](#Time) | `time` | The date and time of the observation. This is needed because the returned vector object requires a valid time value when passed to certain other functions. | -### Returns: Vector +### Returns: [`Vector`](#Vector) A vector in the equatorial system. --- @@ -1657,7 +1657,7 @@ A vector in the equatorial system. | [`Time`](#Time) | `time` | The date and time of the observation. This is needed because the returned vector object requires a valid time value when passed to certain other functions. | | [`Refraction`](#Refraction) | `refraction` | See remarks in function #RefractionAngle. | -### Returns: Vector +### Returns: [`Vector`](#Vector) A vector in the horizontal system: `x` = north, `y` = west, and `z` = zenith (up). --- @@ -1676,6 +1676,6 @@ includes the time, as required by all `Time` objects. | [`Spherical`](#Spherical) | `sphere` | Spherical coordinates to be converted. | | [`Time`](#Time) | `time` | The time that should be included in the returned vector. | -### Returns: Vector +### Returns: [`Vector`](#Vector) The vector form of the supplied spherical coordinates. diff --git a/source/python/astronomy.py b/source/python/astronomy.py index d5fa0080..3e6ff490 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,7 +432,7 @@ class Time: Returns ------- - #Time + Time """ micro = round(math.fmod(second, 1.0) * 1000000) second = math.floor(second - micro/1000000) @@ -451,7 +451,7 @@ class Time: Returns ------- - #Time + Time """ ut = (datetime.datetime.utcnow() - _EPOCH).total_seconds() / 86400.0 return Time(ut) @@ -479,7 +479,7 @@ class Time: Returns ------- - #Time + Time """ return Time(self.ut + days) @@ -496,7 +496,7 @@ class Time: Returns ------- - `datetime` + datetime """ return _EPOCH + datetime.timedelta(days=self.ut) @@ -2176,7 +2176,7 @@ def GeoMoon(time): Returns ------- - #Vector + Vector The Moon's position as a vector in J2000 Cartesian equatorial coordinates. """ @@ -3138,7 +3138,7 @@ def Search(func, context, t1, t2, dt_tolerance_seconds): Returns ------- - #Time or `None` + 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 @@ -3245,7 +3245,7 @@ def HelioVector(body, time): Returns ------- - #Vector + Vector A heliocentric position vector of the center of the given body at the given time. """ @@ -3297,7 +3297,7 @@ def GeoVector(body, time, aberration): Returns ------- - #Vector + Vector A geocentric position vector of the center of the given body. """ if body == Body.Moon: @@ -3379,7 +3379,7 @@ def Equator(body, time, observer, ofdate, aberration): Returns ------- - #EquatorialCoordinates + EquatorialCoordinates Equatorial coordinates in the specified frame of reference. """ gc_observer = _geo_pos(time, observer) @@ -3488,7 +3488,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 @@ -3720,7 +3720,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. @@ -3751,7 +3751,7 @@ def Ecliptic(equ): Returns ------- - #EclipticCoordinates + EclipticCoordinates Ecliptic coordinates in the J2000 frame of reference. """ # Based on NOVAS functions equ2ecl() and equ2ecl_vec(). @@ -3776,7 +3776,7 @@ def EclipticLongitude(body, time): Returns ------- - `float` + float An angular value in degrees indicating the ecliptic longitude of the body. """ if body == Body.Sun: @@ -3802,7 +3802,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. """ @@ -3846,7 +3846,7 @@ def LongitudeFromSun(body, time): Returns ------- - `float` + float An angle in degrees in the range [0, 360). """ if body == Body.Earth: @@ -3921,7 +3921,7 @@ def Elongation(body, time): Returns ------- - #ElongationEvent + ElongationEvent """ angle = LongitudeFromSun(body, time) if angle > 180.0: @@ -3987,7 +3987,7 @@ def SearchRelativeLongitude(body, targetRelLon, startTime): Returns ------- - #Time + Time The date and time of the relative longitude event. """ if body == Body.Earth: @@ -4056,7 +4056,7 @@ def SearchMaxElongation(body, startTime): Returns ------- - #ElongationEvent + ElongationEvent """ if body == Body.Mercury: s1 = 50.0 @@ -4176,7 +4176,7 @@ def SearchSunLongitude(targetLon, startTime, limitDays): Returns ------- - #Time or `None` + Time or `None` """ t2 = startTime.AddDays(limitDays) return Search(_sun_offset, targetLon, startTime, t2, 1.0) @@ -4200,7 +4200,7 @@ def MoonPhase(time): Returns ------- - `float` + float """ return LongitudeFromSun(Body.Moon, time) @@ -4237,7 +4237,7 @@ def SearchMoonPhase(targetLon, startTime, limitDays): Returns ------- - #Time or `None` + Time or `None` """ # To avoid discontinuities in the _moon_offset function causing problems, # we need to approximate when that function will next return 0. @@ -4301,7 +4301,7 @@ def SearchMoonQuarter(startTime): Returns ------- - #MoonQuarter + MoonQuarter """ angle = MoonPhase(startTime) quarter = int(1 + math.floor(angle / 90.0)) % 4 @@ -4326,7 +4326,7 @@ def NextMoonQuarter(mq): Returns ------- - #MoonQuarter + MoonQuarter """ # Skip 6 days past the previous found moon quarter to find the next one. # This is less than the minimum possible increment. @@ -4467,7 +4467,7 @@ def Illumination(body, time): Returns ------- - #IlluminationInfo + IlluminationInfo """ if body == Body.Earth: raise EarthNotAllowedError() @@ -4537,7 +4537,7 @@ def SearchPeakMagnitude(body, startTime): Returns ------- - #IlluminationInfo + IlluminationInfo """ # s1 and s2 are relative longitudes within which peak magnitude of Venus can occur. s1 = 10.0 @@ -4673,7 +4673,7 @@ def SearchHourAngle(body, observer, hourAngle, startTime): Returns ------- - #HourAngleEvent + HourAngleEvent """ if body == Body.Earth: raise EarthNotAllowedError() @@ -4793,7 +4793,7 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): Returns ------- - #Time or `None` + Time or `None` If the rise or set time is found within the specified time window, this function returns that time. Otherwise, it returns `None`. """ @@ -4918,7 +4918,7 @@ def Seasons(year): Returns ------- - #SeasonInfo + SeasonInfo """ mar_equinox = _FindSeasonChange(0, year, 3, 19) jun_solstice = _FindSeasonChange(90, year, 6, 19) @@ -5012,7 +5012,7 @@ def SearchLunarApsis(startTime): Returns ------- - #Apsis + Apsis """ increment = 5.0 # number of days to skip on each iteration t1 = startTime @@ -5071,7 +5071,7 @@ def NextLunarApsis(apsis): Returns ------- - #Apsis + Apsis """ skip = 11.0 # number of days to skip to start looking for next apsis event time = apsis.time.AddDays(skip) @@ -5577,6 +5577,7 @@ def Rotation_EQD_ECL(time): Returns ------- + RotationMatrix A rotation matrix that converts EQD to ECL. """ eqd_eqj = Rotation_EQD_EQJ(time)