The primary API to Calliope is the commandline interface. It can be called from any programming language in the world and can also be used directly from Bash. Great.
As an optimization we could expose the underlying Python API as well. This is how I imagine it working:
each module inside calliope/ contains an api.py file, which defines the public API.
the API is documented using docstrings in the api.py files
sphinx-autodoc is used to generate reference documentation, and we use the existing CALLIOPE_DOCS_BUILD hook so that we don't require the full set of dependencies when building the docs
the cli.py file becomes a wrapper around the api.py files.
The only big downside here is that we'll have mostly duplicate documentation in cli.py and api.py. We may be able to use some clever string substitution to minimize duplication, or we may just have to live with it.
The primary API to Calliope is the commandline interface. It can be called from any programming language in the world and can also be used directly from Bash. Great.
As an optimization we could expose the underlying Python API as well. This is how I imagine it working:
api.pyfile, which defines the public API.api.pyfilesThe only big downside here is that we'll have mostly duplicate documentation in cli.py and api.py. We may be able to use some clever string substitution to minimize duplication, or we may just have to live with it.