Doc improvements

Author: jepler

.gitignore

@@ -16,3 +16,4 @@ bundles
 dist
 **/*.egg-info
 .vscode
+docs/api

docs/api.rst

@@ -0,0 +1,99 @@
+{% if not obj.display %}
+:orphan:
+
+{% endif %}
+:mod:`{{ obj.name }}`
+======={{ "=" * obj.name|length }}
+
+.. py:module:: {{ obj.name }}
+
+{% if obj.docstring %}
+.. autoapi-nested-parse::
+
+   {{ obj.docstring|prepare_docstring|indent(3) }}
+
+{% endif %}
+
+{% block subpackages %}
+{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
+{% if visible_subpackages %}
+Subpackages
+-----------
+.. toctree::
+   :maxdepth: 1
+
+{% for subpackage in visible_subpackages %}
+   {{ subpackage.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block submodules %}
+{% set visible_submodules = obj.submodules|selectattr("display")|list %}
+{% if visible_submodules %}
+Submodules
+----------
+.. toctree::
+   :maxdepth: 1
+
+{% for submodule in visible_submodules %}
+   {{ submodule.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block content %}
+{% if obj.all is not none %}
+{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %}
+{% elif obj.type is equalto("package") %}
+{% set visible_children = obj.children|selectattr("display")|list %}
+{% else %}
+{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
+{% endif %}
+{% if visible_children %}
+{{ obj.type|title }} Contents
+{{ "-" * obj.type|length }}---------
+
+
+{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
+{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
+
+{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
+
+{% block classes scoped %}
+{% if visible_classes %}
+Classes
+~~~~~~~
+
+.. autoapisummary::
+
+{% for klass in visible_classes %}
+   {{ klass.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+
+{% block functions scoped %}
+{% if visible_functions %}
+Functions
+~~~~~~~~~
+
+.. autoapisummary::
+
+{% for function in visible_functions %}
+   {{ function.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% endif %}
+{% for obj_item in visible_children %}
+{{ obj_item.rendered|indent(0) }}
+{% endfor %}
+{% endif %}
+{% endblock %}

docs/autoapi/templates/python/module.rst

@@ -15,18 +15,26 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
+    "autoapi.extension",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
 ]
 
-# TODO: Please Read!
-# Uncomment the below if you use native CircuitPython modules such as
-# digitalio, micropython and busio. List the modules you use. Without it, the
-# autodoc module docs will fail to generate with a warning.
-# autodoc_mock_imports = ["digitalio", "busio"]
-
+autoapi_keep_files = True
+autoapi_dirs = ["../jepler_udecimal"]
+autoapi_add_toctree_entry = True
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "special-members",
+    "show-module-summary",
+]
+autoapi_python_class_content = "both"
+autoapi_python_use_implicit_namespaces = True
+autoapi_template_dir = "autoapi/templates"
+autoapi_root = "api"
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.4", None),
@@ -71,6 +79,7 @@
     ".DS_Store",
     ".env",
     "CODE_OF_CONDUCT.md",
+    "autoapi",
 ]
 
 # The reST default role (used for this markup: `text`) to use for all

docs/conf.py

@@ -8,15 +8,13 @@ Table of Contents
     :hidden:
 
     self
+    api/index.rst
 
 .. toctree::
     :caption: API Reference
-    :maxdepth: 3
-
-    api
+    :maxdepth: 4
 
-.. toctree::
-    :caption: Tutorials
+    api/jepler_udecimal/index.rst
 
 .. toctree::
     :caption: Other Links

docs/index.rst

@@ -0,0 +1,7 @@
+sphinx<4
+recommonmark==0.6.0
+sphinxcontrib-svg2pdfconverter==0.1.0
+astroid
+sphinx-autoapi
+isort
+black

docs/requirements.txt

@@ -22,6 +22,9 @@
 CircuitPython as well as standard Python, though you should probably
 use the built in decimal module on standard Python.
 
+It still requires a fairly beefy mcu to run.  Importing jepler_udecimal
+on an nRF52840 uses about 52kB of heap.
+
 * Author(s): jepler
 
 Implementation Notes
@@ -37,9 +40,9 @@
   https://github.com/adafruit/circuitpython/releases
 
 This is an implementation of decimal floating point arithmetic based on
-the [General Decimal Arithmetic Specification](http://speleotrove.com/decimal/decarith.html) and [IEEE standard 854-1987](http://en.wikipedia.org/wiki/IEEE_854-1987).
+the `General Decimal Arithmetic Specification <http://speleotrove.com/decimal/decarith.html>`_ and `IEEE standard 854-1987 <http://en.wikipedia.org/wiki/IEEE_854-1987>`_.
 
-Decimal floating point has finite precision with arbitrarily large bounds.
+`Decimal` floating point has finite precision with arbitrarily large bounds.
 
 The purpose of this module is to support arithmetic using familiar
 "schoolhouse" rules and to avoid some of the tricky representation
@@ -943,10 +946,12 @@ def __ge__(self, other, context=None):
     def compare(self, other, context=None):
         """Compare self to other.  Return a decimal value:
 
+        =============== === ==============
         a or b is a NaN ==> Decimal('NaN')
         a < b           ==> Decimal('-1')
         a == b          ==> Decimal('0')
         a > b           ==> Decimal('1')
+        =============== === ==============
         """
         other = _convert_other(other, raiseit=True)
 
@@ -3272,16 +3277,17 @@ def number_class(self, context=None):
         """Returns an indication of the class of self.
 
         The class is one of the following strings:
-          sNaN
-          NaN
-          -Infinity
-          -Normal
-          -Subnormal
-          -Zero
-          +Zero
-          +Subnormal
-          +Normal
-          +Infinity
+
+        * sNaN
+        * NaN
+        * -Infinity
+        * -Normal
+        * -Subnormal
+        * -Zero
+        * +Zero
+        * +Subnormal
+        * +Normal
+        * +Infinity
         """
         if self.is_snan():
             return "sNaN"
@@ -4531,16 +4537,17 @@ def number_class(self, a):
         """Returns an indication of the class of the operand.
 
         The class is one of the following strings:
-          -sNaN
-          -NaN
-          -Infinity
-          -Normal
-          -Subnormal
-          -Zero
-          +Zero
-          +Subnormal
-          +Normal
-          +Infinity
+
+        * -sNaN
+        * -NaN
+        * -Infinity
+        * -Normal
+        * -Subnormal
+        * -Zero
+        * +Zero
+        * +Subnormal
+        * +Normal
+        * +Infinity
 
         >>> c = ExtendedContext.copy()
         >>> c.Emin = -999
@@ -4595,26 +4602,11 @@ def plus(self, a):
         return a.__pos__(context=self)
 
     def power(self, a, b):
-        """Raises a to the power of b, to modulo if given.
-
-        With two arguments, compute a**b.  If a is negative then b
-        must be integral.  The result will be inexact unless b is
-        integral and the result is finite and can be expressed exactly
-        in 'precision' digits.
-
-        With three arguments, compute (a**b) % modulo.  For the
-        three argument form, the following restrictions on the
-        arguments hold:
-
-         - all three arguments must be integral
-         - b must be nonnegative
-         - at least one of a or b must be nonzero
-         - modulo must be nonzero and have at most 'precision' digits
-
-        The result of pow(a, b, modulo) is identical to the result
-        that would be obtained by computing (a**b) % modulo with
-        unbounded precision, but is computed more efficiently.  It is
-        always exact.
+        """Raises a to the power of b
+
+        If a is negative then b must be integral.  The result will be inexact
+        unless b is integral and the result is finite and can be expressed
+        exactly in 'precision' digits.
 
         >>> c = ExtendedContext.copy()
         >>> c.Emin = -999

jepler_udecimal/__init__.py

@@ -16,7 +16,7 @@
 """
 Trig functions using jepler_udecimal
 
-Importing this module adds the relevant methods to the Decimal object.
+Importing this module adds the relevant methods to the `Decimal` object.
 
 Generally speaking, these routines increase the precision by some amount,
 perform argument range reduction followed by evaluation of a taylor polynomial,
@@ -48,7 +48,7 @@
 
 from . import Decimal, localcontext
 
-__all__ = ["atan", "sin", "cos"]
+__all__ = ["acos", "asin", "atan", "cos", "sin", "tan"]
 
 _point2 = Decimal(".2")
 
@@ -190,9 +190,12 @@ def acos(x, context=None):
         return r
 
 
-Decimal.tan = tan
-Decimal.sin = sin
-Decimal.cos = cos
-Decimal.atan = atan
-Decimal.asin = asin
-Decimal.acos = acos
+# pylint: disable=using-constant-test
+# This stops a doc-building error in autoapi
+if 1:
+    Decimal.tan = tan
+    Decimal.sin = sin
+    Decimal.cos = cos
+    Decimal.atan = atan
+    Decimal.asin = asin
+    Decimal.acos = acos