Auto-documentation for CLI and API

.gitignore

@@ -12,3 +12,9 @@ __pycache__/
 args.json
 temp.json
 **/*.DS_Store
+api_docs/build/
+api_docs/make.bat
+api_docs/Makefile
+cli_docs/*
+!cli_docs/generate_cli_docs.py
+!cli_docs/README.MD

api_docs/README.md

@@ -0,0 +1,43 @@
+# **Auto-documentation for Aerie-CLI API:**
+
+The Aerie-CLI API provides a user-extendable API for interacting with an instance of Aerie. 
+
+The following steps generate documentation for the files in `src/aerie_cli` (excluding the `/command` directory and `app.py`). 
+
+<br>
+
+## **How to Generate Documentation Using Sphinx-CLI**
+1. Make sure you have `sphinx` is installed: 
+
+    ```
+    pip install sphinx
+    ```
+
+2. Navigate to the outer `aerie-cli` directory: 
+    ```
+    cd aerie-cli
+    ```
+
+3. Using [`sphinx-apidoc`](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html), generate the for files in `src/aerie_cli` into the `api_docs` directory.  
+    ```
+    sphinx-apidoc -o ./api_docs/source ./src/aerie_cli
+    ```
+
+4. View this documentation with the `index.html` file located in `api_docs/build/html`.
+
+<br>
+
+## **Modify the Documentation Output**
+To edit the format of the html output, you can modify the following files using the directives from the sphinx `autodoc` extension ([`sphinx.ext.autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)): 
+
+1. [`aerie_cli.rst`](source/aerie_cli.rst): Contains files in the src/aerie_cli directory (excluding app.py). Lists subpackages as aerie_cli.schemas and aerie_cli.utils. 
+2. [`aerie_cli.schemas.rst`](source/aerie_cli.schemas.rst): Contains the files in the src/aerie_cli/schemas directory. 
+3. [`aerie_cli.utils.rst`](source/aerie_cli.schemas.rst): Contains the files in the src/aerie_cli/utils directory. 
+
+<br>
+
+## **Format Docstrings**
+Sphinx autodoc can correctly generate docs from two formatting options: 
+
+1. Follow the [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). Many of the docstrings already in the app follow this style. 
+2. Or, an alternative is following the [Sphinx Docstring format](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html).

api_docs/source/aerie_cli.rst

@@ -0,0 +1,38 @@
+aerie\_cli package
+==================
+
+.. Submodules
+.. ----------
+
+aerie\_cli.aerie\_client module
+-------------------------------
+
+.. automodule:: aerie_cli.aerie_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+aerie\_cli.aerie\_host module
+-----------------------------
+
+.. automodule:: aerie_cli.aerie_host
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+aerie\_cli.persistent module
+----------------------------
+
+.. automodule:: aerie_cli.persistent
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   aerie_cli.schemas
+   aerie_cli.utils

api_docs/source/aerie_cli.schemas.rst

@@ -0,0 +1,21 @@
+aerie\_cli.schemas package
+==========================
+
+.. Submodules
+.. ----------
+
+aerie\_cli.schemas.api module
+-----------------------------
+
+.. automodule:: aerie_cli.schemas.api
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+aerie\_cli.schemas.client module
+--------------------------------
+
+.. automodule:: aerie_cli.schemas.client
+   :members:
+   :undoc-members:
+   :show-inheritance:

api_docs/source/aerie_cli.utils.rst

@@ -0,0 +1,37 @@
+aerie\_cli.utils package
+========================
+
+.. Submodules
+.. ----------
+
+aerie\_cli.utils.configurations module
+--------------------------------------
+
+.. automodule:: aerie_cli.utils.configurations
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+aerie\_cli.utils.prompts module
+-------------------------------
+
+.. automodule:: aerie_cli.utils.prompts
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+aerie\_cli.utils.serialization module
+-------------------------------------
+
+.. automodule:: aerie_cli.utils.serialization
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+aerie\_cli.utils.sessions module
+--------------------------------
+
+.. automodule:: aerie_cli.utils.sessions
+   :members:
+   :undoc-members:
+   :show-inheritance:

api_docs/source/conf.py

@@ -0,0 +1,32 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Aerie-CLI-API-Docs'
+copyright = '2023, zoe'
+author = 'zoe'
+release = '0.1'
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon', "sphinx.ext.doctest"]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']

api_docs/source/index.rst

@@ -0,0 +1,10 @@
+Aerie CLI API's documentation!
+==============================================
+
+.. toctree::
+   :maxdepth: 5
+   :caption: Contents:
+
+   aerie_cli
+   aerie_cli.schemas
+   aerie_cli.utils

cli_docs/README.md

@@ -0,0 +1,39 @@
+# **Aerie-CLI Documentation**
+
+## **CLI Commands**: 
+<!-- - [`command_context`](command_context.md) -->
+- [`app`](app.md)
+- [`configurations`](configurations.md)
+- [`constraints`](constraints.md)
+- [`expansion`](expansion.md)
+- [`metadata`](metadata.md)
+- [`models`](models.md)
+- [`plans`](plans.md)
+- [`scheduling`](scheduling.md)
+
+---
+
+## **How to Generate Documentation**
+### **Documentation for Individual Command with Typer CLI** 
+Usage:
+
+```$ typer script.py utils docs --name TEXT --output FILE```
+
+Subcommands:
+- `utils`
+- `docs`
+
+Options: 
+- `--name TEXT` : name of the CLI program to use in docs
+    - *Ex: `--name 'aerie-cli plans'`*
+- `--output FILE` : output file to write docs to
+    - *Ex: `--output 'plans.md'`*
+
+<br>
+
+### **Documentation for All Individual Commands**
+Generate documentation for all Aerie-CLI commands using the `generate_cli_docs` script.
+
+Usage: 
+
+```$ python3 generate_cli_docs.py```

cli_docs/generate_cli_docs.py

@@ -0,0 +1,42 @@
+"""
+Generates docs for CLI command files to Markdown files in /cli_docs folder
+    ** Note - run while in `cli_docs/` directory so files generate in correct spot
+"""
+
+import subprocess
+import os
+import sys
+import typer
+
+path_to_commands = "../src/aerie_cli/commands"
+
+#app commands from /commands directory
+for filename in os.listdir(path_to_commands):
+    total_filepath = os.path.join(path_to_commands, filename)
+    if os.path.isfile(total_filepath):
+        input_name = filename[:-3]
+
+        #skip command_context.py for now
+        if(filename != 'command_context.py'):
+            #create a new file if doesn't exist 
+            output_file = open(input_name + ".md", "w")
+
+            try:
+                #run typer for all files that uses typer's '@app.command'
+                subprocess.run(['typer', total_filepath, 'utils', 'docs', 
+                                "--name", 'aerie-cli ' + input_name ,
+                                "--output", input_name + ".md"])
+            except subprocess.CalledProcessError as e: 
+                print(f"Subprocess failed for {filename}: {e}")
+
+#generate docs for app.py
+path_to_app = "../src/aerie_cli/app.py"
+
+try:
+    output_file = open("app.md", "w")
+    #run typer for all files that uses typer's '@app.command'
+    subprocess.run(['typer', path_to_app, 'utils', 'docs', 
+                    "--name", 'aerie-cli' ,
+                    "--output", "app.md"])
+except subprocess.CalledProcessError as e: 
+    print(f"Subprocess failed for {filename}: {e}")