API docs are stale

[michaeldiamant]

Problem

While considering https://github.com/algorand/js-algorand-sdk/issues/709, @algochoi pointed out https://py-algorand-sdk.readthedocs.io/en/latest/ does not contain recently introduced classes (e.g. https://github.com/algorand/py-algorand-sdk/blob/develop/algosdk/box_reference.py).

The story requests:

• Update docs to be current.
• Triage to identify if there's easier ways to keep docs in-sync.
  • Current process relies on manual creation of rst files.
  • If improvements are identified, port to pyteal or open an issue.

Solution

Dependencies

Urgency

[algochoi]

Could investigate something like: https://github.com/copier-org/copier

[tzaffi]

The story requests:

• Update docs to be current.

#481 addresses the first concern

• Triage to identify if there's easier ways to keep docs in-sync.

  • Current process relies on manual creation of rst files.

We can automate as follows:

Create a module RST template:

module_name = "constants" 

template = """{name}
{equals}

.. automodule:: algosdk.{name}
   :members:
   :undoc-members:
   :show-inheritance:
"""

# Format the template
content = template.format(name=module_name, equals='='*len(module_name))

# Write to the file
with open(f"{module_name}.rst", 'w') as f:
    f.write(content)

[tzaffi]

• Current process relies on manual creation of rst files.
• If improvements are identified, port to pyteal or open an issue.

We can also write a docs_test.py which simply looks for algosdk.* modules and asserts that there aren't any unaccounted for in docs/algosdk/index.rst or docs/algosdk/*.rst.