From 033a2a1b53ec05d2bdd5967774831a31fb03ad95 Mon Sep 17 00:00:00 2001 From: Don Cross Date: Wed, 10 Jul 2019 21:57:07 -0400 Subject: [PATCH] pydown: Split classes into regular classes, enums, and errors. Will generate different Markdown for my regular classes, enumerated types, and error types. Found out that 'from enum import IntEnum' pulls IntEnum into the astronomy module and causes us to try to generate documentation for it. Just keep it in the enum module. Removed spurious dump of JavaScript README.md when verify_clean fails. --- generate/template/astronomy.py | 18 +++--- generate/verify_clean | 2 - pydown/pydown.py | 42 +++++++++++-- source/python/README.md | 110 ++++----------------------------- source/python/astronomy.py | 18 +++--- 5 files changed, 66 insertions(+), 124 deletions(-) diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index fafb8fae..d91abaaf 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -33,7 +33,7 @@ https://github.com/cosinekitty/astronomy import math import datetime -from enum import IntEnum, unique +import enum _PI2 = 2.0 * math.pi _EPOCH = datetime.datetime(2000, 1, 1, 12) @@ -83,8 +83,8 @@ class Vector: def Length(self): return math.sqrt(self.x**2 + self.y**2 + self.z**2) -@unique -class Body(IntEnum): +@enum.unique +class Body(enum.IntEnum): Invalid = -1 """A placeholder value for an unknown, undefined, or invalid body.""" @@ -1016,8 +1016,8 @@ def Equator(body, time, observer, ofdate, aberration): datevect = _nutation(time, 0, temp) return _vector2radec(datevect) -@unique -class Refraction(IntEnum): +@enum.unique +class Refraction(enum.IntEnum): Airless = 0 Normal = 1 JplHorizons = 2 @@ -1644,8 +1644,8 @@ def SearchHourAngle(body, observer, hourAngle, startTime): delta_days = (delta_sidereal_hours / 24.0) * _SOLAR_DAYS_PER_SIDEREAL_DAY time = time.AddDays(delta_days) -@unique -class Direction(IntEnum): +@enum.unique +class Direction(enum.IntEnum): Rise = +1 Set = -1 @@ -1764,8 +1764,8 @@ def _distance_slope(direction, time): dist2 = _MoonDistance(t2) return direction * (dist2 - dist1) / dt -@unique -class ApsisKind(IntEnum): +@enum.unique +class ApsisKind(enum.IntEnum): Pericenter = 0 Apocenter = 1 Invalid = 2 diff --git a/generate/verify_clean b/generate/verify_clean index a21432a6..c099870e 100755 --- a/generate/verify_clean +++ b/generate/verify_clean @@ -5,8 +5,6 @@ if [[ ! -z "$(git status --porcelain)" ]]; then echo "" echo "Diff output:" git diff - echo "--- README.md ---" - cat ../source/js/README.md exit 1 fi echo "verify_clean: OK" diff --git a/pydown/pydown.py b/pydown/pydown.py index 82b40527..6bff87c8 100755 --- a/pydown/pydown.py +++ b/pydown/pydown.py @@ -4,6 +4,7 @@ import os import re import importlib import inspect +import enum def PrintUsage(): print(""" @@ -65,7 +66,7 @@ class DocInfo: for line in lines: if re.match(r'^\-+$', line): continue - if line in ['Parameters', 'Returns', 'Example', 'Examples', 'Properties']: + if line in ['Parameters', 'Returns', 'Example', 'Examples', 'Attributes']: mode = line continue if line.strip() == '': @@ -73,7 +74,7 @@ class DocInfo: continue if mode == 'Parameters': currentParm = self.ProcessParmAttrLine(line, currentParm, self.parameters) - elif mode == 'Properties': + elif mode == 'Attributes': currentAttr = self.ProcessParmAttrLine(line, currentAttr, self.attributes) elif mode == 'Returns': pass @@ -152,12 +153,19 @@ def Markdown(module): md = '' funclist = [] classlist = [] + enumlist = [] + errlist = [] for name, obj in inspect.getmembers(module): if not name.startswith('_'): if inspect.isfunction(obj): funclist.append(obj) elif inspect.isclass(obj): - classlist.append(obj) + if issubclass(obj, enum.Enum): + enumlist.append(obj) + elif issubclass(obj, Exception): + errlist.append(obj) + else: + classlist.append(obj) elif inspect.ismodule(obj): pass # ignore other modules pulled in else: @@ -165,13 +173,35 @@ def Markdown(module): md += '---\n' md += '\n' - md += '\n' - md += '## Functions\n' + md += '\n' + md += '## Classes\n' md += '\n' - for c in classlist: md += MdClass(c) + if False: # not yet ready to generate Markdown for enumerated types + md += '---\n' + md += '\n' + md += '\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' + md += '\n' + md += '\n' + md += '## Error Types\n' + md += '\n' + for c in errlist: + md += MdErrType(c) + + md += '---\n' + md += '\n' + md += '\n' + md += '## Functions\n' + md += '\n' for func in funclist: md += MdFunction(func) diff --git a/source/python/README.md b/source/python/README.md index 773fd984..808a00fd 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -1,87 +1,7 @@ --- - -## Functions - - ---- - - -### class ApsisKind - - - - ---- - - -### class BadVectorError - - - - ---- - - -### class Body - - - - ---- - - -### class Direction - - - - ---- - - -### class EarthNotAllowedError - - - - ---- - - -### class Error - - - - ---- - - -### class IntEnum - - - - ---- - - -### class InternalError - - - - ---- - - -### class InvalidBodyError - - - - ---- - - -### class NoConvergeError - - + +## Classes --- @@ -94,14 +14,6 @@ ---- - - -### class Refraction - - - - --- @@ -113,9 +25,19 @@ | --- | --- | --- | | `float` | `ut` | UT1/UTC number of days since noon on January 1, 2000. See the `ut` attribute of this class for more details. | +| Type | Attribute | Description | +| --- | --- | --- | +| `float` | `ut` | The floating point number of days of Universal Time since noon UTC January 1, 2000. Astronomy Engine approximates UTC and UT1 as being the same thing, although they are not exactly equivalent; UTC and UT1 can disagree by up to 0.9 seconds. This approximation is sufficient for the accuracy requirements of Astronomy Engine. Universal Time Coordinate (UTC) is the international standard for legal and civil timekeeping and replaces the older Greenwich Mean Time (GMT) standard. UTC is kept in sync with unpredictable observed changes in the Earth's rotation by occasionally adding leap seconds as needed. UT1 is an idealized time scale based on observed rotation of the Earth, which gradually slows down in an unpredictable way over time, due to tidal drag by the Moon and Sun, large scale weather events like hurricanes, and internal seismic and convection effects. Conceptually, UT1 drifts from atomic time continuously and erratically, whereas UTC is adjusted by a scheduled whole number of leap seconds as needed. The value in `ut` is appropriate for any calculation involving the Earth's rotation, such as calculating rise/set times, culumination, and anything involving apparent sidereal time. Before the era of atomic timekeeping, days based on the Earth's rotation were often known as *mean solar days*. | +| `float` | `tt` | Terrestrial Time days since noon on January 1, 2000. Terrestrial Time is an atomic time scale defined as a number of days since noon on January 1, 2000. In this system, days are not based on Earth rotations, but instead by the number of elapsed [SI seconds](https://physics.nist.gov/cuu/Units/second.html) divided by 86400. Unlike `ut`, `tt` increases uniformly without adjustments for changes in the Earth's rotation. The value in `tt` is used for calculations of movements not involving the Earth's rotation, such as the orbits of planets around the Sun, or the Moon around the Earth. Historically, Terrestrial Time has also been known by the term *Ephemeris Time* (ET). | +--- + + +## Functions + + --- @@ -143,11 +65,3 @@ - ---- - - -### unique(enumeration) - - - diff --git a/source/python/astronomy.py b/source/python/astronomy.py index 44c7355a..2fd91895 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -33,7 +33,7 @@ https://github.com/cosinekitty/astronomy import math import datetime -from enum import IntEnum, unique +import enum _PI2 = 2.0 * math.pi _EPOCH = datetime.datetime(2000, 1, 1, 12) @@ -83,8 +83,8 @@ class Vector: def Length(self): return math.sqrt(self.x**2 + self.y**2 + self.z**2) -@unique -class Body(IntEnum): +@enum.unique +class Body(enum.IntEnum): Invalid = -1 """A placeholder value for an unknown, undefined, or invalid body.""" @@ -3077,8 +3077,8 @@ def Equator(body, time, observer, ofdate, aberration): datevect = _nutation(time, 0, temp) return _vector2radec(datevect) -@unique -class Refraction(IntEnum): +@enum.unique +class Refraction(enum.IntEnum): Airless = 0 Normal = 1 JplHorizons = 2 @@ -3705,8 +3705,8 @@ def SearchHourAngle(body, observer, hourAngle, startTime): delta_days = (delta_sidereal_hours / 24.0) * _SOLAR_DAYS_PER_SIDEREAL_DAY time = time.AddDays(delta_days) -@unique -class Direction(IntEnum): +@enum.unique +class Direction(enum.IntEnum): Rise = +1 Set = -1 @@ -3825,8 +3825,8 @@ def _distance_slope(direction, time): dist2 = _MoonDistance(t2) return direction * (dist2 - dist1) / dt -@unique -class ApsisKind(IntEnum): +@enum.unique +class ApsisKind(enum.IntEnum): Pericenter = 0 Apocenter = 1 Invalid = 2