From 4cc2a14a38c0ea833e2650277c03da0e98d22c97 Mon Sep 17 00:00:00 2001 From: Don Cross Date: Thu, 1 Apr 2021 09:39:51 -0400 Subject: [PATCH] Python docs: provide mechanism for documenting constants. Python docstrings don't work for variables, so I hacked a special comment format for helping pydown generate Markdown text for the README.md for the exported constant KM_PER_AU, or any other constants I may want to expose in the future. --- demo/python/astronomy.py | 4 ++-- generate/template/astronomy.py | 4 ++-- pydown/py_prefix.md | 1 + pydown/pydown.py | 33 ++++++++++++++++++++++++++++++--- source/python/README.md | 15 ++++++++++++++- source/python/astronomy.py | 4 ++-- 6 files changed, 51 insertions(+), 10 deletions(-) diff --git a/demo/python/astronomy.py b/demo/python/astronomy.py index 3d262be2..f7a93f47 100644 --- a/demo/python/astronomy.py +++ b/demo/python/astronomy.py @@ -36,7 +36,7 @@ import datetime import enum import re -KM_PER_AU = 1.4959787069098932e+8 +KM_PER_AU = 1.4959787069098932e+8 # The number of kilometers per astronomical unit. _CalcMoonCount = 0 @@ -3800,7 +3800,7 @@ def ObserverVector(time, observer, ofdate): The returned vector has components expressed in astronomical units (AU). To convert to kilometers, multiply the `x`, `y`, and `z` values by - the constant value `KM_PER_AU`. + the constant value #KM_PER_AU. Parameters ---------- diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index f3dd9960..f7a983f8 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -36,7 +36,7 @@ import datetime import enum import re -KM_PER_AU = 1.4959787069098932e+8 +KM_PER_AU = 1.4959787069098932e+8 # The number of kilometers per astronomical unit. _CalcMoonCount = 0 @@ -1903,7 +1903,7 @@ def ObserverVector(time, observer, ofdate): The returned vector has components expressed in astronomical units (AU). To convert to kilometers, multiply the `x`, `y`, and `z` values by - the constant value `KM_PER_AU`. + the constant value #KM_PER_AU. Parameters ---------- diff --git a/pydown/py_prefix.md b/pydown/py_prefix.md index fe38e149..33f9aa76 100644 --- a/pydown/py_prefix.md +++ b/pydown/py_prefix.md @@ -14,6 +14,7 @@ To get started quickly, here are some [examples](../../demo/python/). ## Contents - [Topic Index](#topics) +- [Constants](#constants) - [Classes](#classes) - [Enumerated Types](#enumerations) - [Error Types](#errors) diff --git a/pydown/pydown.py b/pydown/pydown.py index 237798e9..2de9a3df 100755 --- a/pydown/pydown.py +++ b/pydown/pydown.py @@ -34,7 +34,7 @@ def HtmlEscape(text): return text def SymbolLink(name): - # Special case: Search and related functions have return type = "Time or `None`" + # 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`' @@ -264,7 +264,7 @@ def MdErrType(c): Fail('No documentation for exception class ' + c.__name__) return md -def Markdown(module): +def Markdown(module, const_md): md = '' funclist = [] classlist = [] @@ -286,6 +286,13 @@ def Markdown(module): else: print('pydown.py WARNING: ignoring', name) + md += '---\n' + md += '\n' + md += '\n' + md += '## Constants\n' + md += '\n' + md += const_md + md += '---\n' md += '\n' md += '\n' @@ -324,6 +331,25 @@ def Markdown(module): return md + +def ParseConstants(inPythonFileName): + md = '' + with open(inPythonFileName) as infile: + for line in infile: + parts = line.split('#') + if len(parts) == 2: + code = parts[0].strip() + doc = parts[1].strip() + tokens = code.split() + if len(tokens) >= 3 and tokens[1] == '=': + symbol = tokens[0] + md += '\n---\n\n' + md += '\n'.format(symbol) + md += '### `{}`\n\n'.format(code) + md += '**{}**\n\n'.format(doc) + return md + + def main(): if len(sys.argv) != 4: return PrintUsage() @@ -341,7 +367,8 @@ def main(): prefix = infile.read() module = LoadModule(inPythonFileName) - md = Markdown(module) + const_md = ParseConstants(inPythonFileName) + md = Markdown(module, const_md) with open(outMarkdownFileName, 'wt') as outfile: outfile.write(prefix) diff --git a/source/python/README.md b/source/python/README.md index fb64a635..48bf1c70 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -14,6 +14,7 @@ To get started quickly, here are some [examples](../../demo/python/). ## Contents - [Topic Index](#topics) +- [Constants](#constants) - [Classes](#classes) - [Enumerated Types](#enumerations) - [Error Types](#errors) @@ -146,6 +147,18 @@ these are used in function and type names. --- + +## Constants + +--- + + +### `KM_PER_AU = 1.4959787069098932e+8` + +**The number of kilometers per astronomical unit.** + +--- + ## Classes @@ -1482,7 +1495,7 @@ The caller may pass `ofdate` as `True` to return coordinates relative to the Ear equator at the specified time, or `False` to use the J2000 equator. The returned vector has components expressed in astronomical units (AU). To convert to kilometers, multiply the `x`, `y`, and `z` values by -the constant value `KM_PER_AU`. +the constant value [`KM_PER_AU`](#KM_PER_AU). | Type | Parameter | Description | | --- | --- | --- | diff --git a/source/python/astronomy.py b/source/python/astronomy.py index 3d262be2..f7a93f47 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -36,7 +36,7 @@ import datetime import enum import re -KM_PER_AU = 1.4959787069098932e+8 +KM_PER_AU = 1.4959787069098932e+8 # The number of kilometers per astronomical unit. _CalcMoonCount = 0 @@ -3800,7 +3800,7 @@ def ObserverVector(time, observer, ofdate): The returned vector has components expressed in astronomical units (AU). To convert to kilometers, multiply the `x`, `y`, and `z` values by - the constant value `KM_PER_AU`. + the constant value #KM_PER_AU. Parameters ----------