diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py
index 03c715dd..eada36b1 100644
--- a/generate/template/astronomy.py
+++ b/generate/template/astronomy.py
@@ -157,26 +157,48 @@ _PlanetOrbitalPeriod = [
]
class Error(Exception):
+ """Indicates an error in an astronomical calculation."""
def __init__(self, message):
Exception.__init__(self, message)
class EarthNotAllowedError(Error):
+ """The Earth is not allowed as the celestial body in this calculation."""
def __init__(self):
Error.__init__(self, 'The Earth is not allowed as the body.')
class InvalidBodyError(Error):
+ """The celestial body is not allowed for this calculation."""
def __init__(self):
Error.__init__(self, 'Invalid astronomical body.')
class BadVectorError(Error):
+ """A vector magnitude is too small to have a direction in space."""
def __init__(self):
Error.__init__(self, 'Vector is too small to have a direction.')
class InternalError(Error):
+ """An internal error occured that should be reported as a bug.
+
+ Indicates an unexpected and unrecoverable condition occurred.
+ If you encounter this error using Astronomy Engine, it would be very
+ helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues)
+ page on GitHub. Please include a copy of the stack trace, along with a description
+ of how to reproduce the error. This will help improve the quality of
+ Astronomy Engine for everyone! (Thank you in advance from the author.)
+ """
def __init__(self):
Error.__init__(self, 'Internal error - please report issue at https://github.com/cosinekitty/astronomy/issues')
class NoConvergeError(Error):
+ """A numeric solver did not converge.
+
+ Indicates that there was a failure of a numeric solver to converge.
+ If you encounter this error using Astronomy Engine, it would be very
+ helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues)
+ page on GitHub. Please include a copy of the stack trace, along with a description
+ of how to reproduce the error. This will help improve the quality of
+ Astronomy Engine for everyone! (Thank you in advance from the author.)
+ """
def __init__(self):
Error.__init__(self, 'Numeric solver did not converge - please report issue at https://github.com/cosinekitty/astronomy/issues')
@@ -472,7 +494,7 @@ def _vector2radec(pos):
if xyproj == 0.0:
if pos[2] == 0.0:
# Indeterminate coordinates: pos vector has zero length.
- raise Error('Cannot convert vector to polar coordinates')
+ raise BadVectorError()
ra = 0.0
if pos[2] < 0.0:
dec = -90.0
diff --git a/pydown/pydown.py b/pydown/pydown.py
index f5b80c01..47c1dce9 100755
--- a/pydown/pydown.py
+++ b/pydown/pydown.py
@@ -197,13 +197,27 @@ def MdEnumType(c):
md += '---\n'
md += '\n'
md += '\n'.format(c.__name__)
- md += '### ' + c.__name__ + '\n'
+ md += '### enum ' + c.__name__ + '\n'
info = DocInfo(doc)
info.VerifyEnum(set(c.__members__))
md += info.Markdown()
md += '\n'
return md
+def MdErrType(c):
+ md = ''
+ doc = inspect.getdoc(c)
+ if doc:
+ md += '\n'
+ md += '---\n'
+ md += '\n'
+ md += '\n'.format(c.__name__)
+ md += '### ' + c.__name__ + '\n'
+ info = DocInfo(doc)
+ md += info.Markdown()
+ md += '\n'
+ return md
+
def Markdown(module):
md = ''
funclist = []
@@ -242,14 +256,13 @@ def Markdown(module):
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 += '## Error Types\n'
+ md += '\n'
+ for c in errlist:
+ md += MdErrType(c)
md += '---\n'
md += '\n'
diff --git a/source/python/README.md b/source/python/README.md
index 6b5a0d08..176c4daa 100644
--- a/source/python/README.md
+++ b/source/python/README.md
@@ -51,7 +51,7 @@ dates and times represented by `Time` objects.
---
-### ApsisKind
+### enum ApsisKind
**Represents whether a satellite is at a closest or farthest point in its orbit.**
@@ -72,7 +72,7 @@ two cases applies to a particular apsis event.
---
-### Body
+### enum Body
**The celestial bodies supported by Astronomy Engine calculations.**
@@ -96,7 +96,7 @@ two cases applies to a particular apsis event.
---
-### Direction
+### enum Direction
**Indicates whether a body is rising above or setting below the horizon.**
@@ -115,7 +115,7 @@ and `Direction.Set` is used to find sunset times.
---
-### Refraction
+### enum Refraction
**Selects if/how to correct for atmospheric refraction.**
@@ -131,6 +131,91 @@ as seen by an observer on the surface of the Earth.
| `JplHorizons` | Used only for compatibility testing with JPL Horizons online tool. |
+---
+
+
+## Error Types
+
+
+---
+
+
+### BadVectorError
+
+A vector magnitude is too small to have a direction in space.
+
+
+
+
+
+---
+
+
+### EarthNotAllowedError
+
+The Earth is not allowed as the celestial body in this calculation.
+
+
+
+
+
+---
+
+
+### Error
+
+Indicates an error in an astronomical calculation.
+
+
+
+
+
+---
+
+
+### InternalError
+
+**An internal error occured that should be reported as a bug.**
+
+Indicates an unexpected and unrecoverable condition occurred.
+If you encounter this error using Astronomy Engine, it would be very
+helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues)
+page on GitHub. Please include a copy of the stack trace, along with a description
+of how to reproduce the error. This will help improve the quality of
+Astronomy Engine for everyone! (Thank you in advance from the author.)
+
+
+
+
+
+---
+
+
+### InvalidBodyError
+
+The celestial body is not allowed for this calculation.
+
+
+
+
+
+---
+
+
+### NoConvergeError
+
+**A numeric solver did not converge.**
+
+Indicates that there was a failure of a numeric solver to converge.
+If you encounter this error using Astronomy Engine, it would be very
+helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues)
+page on GitHub. Please include a copy of the stack trace, along with a description
+of how to reproduce the error. This will help improve the quality of
+Astronomy Engine for everyone! (Thank you in advance from the author.)
+
+
+
+
---
diff --git a/source/python/astronomy.py b/source/python/astronomy.py
index a45b2775..f812ba36 100644
--- a/source/python/astronomy.py
+++ b/source/python/astronomy.py
@@ -157,26 +157,48 @@ _PlanetOrbitalPeriod = [
]
class Error(Exception):
+ """Indicates an error in an astronomical calculation."""
def __init__(self, message):
Exception.__init__(self, message)
class EarthNotAllowedError(Error):
+ """The Earth is not allowed as the celestial body in this calculation."""
def __init__(self):
Error.__init__(self, 'The Earth is not allowed as the body.')
class InvalidBodyError(Error):
+ """The celestial body is not allowed for this calculation."""
def __init__(self):
Error.__init__(self, 'Invalid astronomical body.')
class BadVectorError(Error):
+ """A vector magnitude is too small to have a direction in space."""
def __init__(self):
Error.__init__(self, 'Vector is too small to have a direction.')
class InternalError(Error):
+ """An internal error occured that should be reported as a bug.
+
+ Indicates an unexpected and unrecoverable condition occurred.
+ If you encounter this error using Astronomy Engine, it would be very
+ helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues)
+ page on GitHub. Please include a copy of the stack trace, along with a description
+ of how to reproduce the error. This will help improve the quality of
+ Astronomy Engine for everyone! (Thank you in advance from the author.)
+ """
def __init__(self):
Error.__init__(self, 'Internal error - please report issue at https://github.com/cosinekitty/astronomy/issues')
class NoConvergeError(Error):
+ """A numeric solver did not converge.
+
+ Indicates that there was a failure of a numeric solver to converge.
+ If you encounter this error using Astronomy Engine, it would be very
+ helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues)
+ page on GitHub. Please include a copy of the stack trace, along with a description
+ of how to reproduce the error. This will help improve the quality of
+ Astronomy Engine for everyone! (Thank you in advance from the author.)
+ """
def __init__(self):
Error.__init__(self, 'Numeric solver did not converge - please report issue at https://github.com/cosinekitty/astronomy/issues')
@@ -1099,7 +1121,7 @@ def _vector2radec(pos):
if xyproj == 0.0:
if pos[2] == 0.0:
# Indeterminate coordinates: pos vector has zero length.
- raise Error('Cannot convert vector to polar coordinates')
+ raise BadVectorError()
ra = 0.0
if pos[2] < 0.0:
dec = -90.0