diff --git a/.gitignore b/.gitignore index d4f86078..8d15dbc7 100644 --- a/.gitignore +++ b/.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 \ No newline at end of file diff --git a/api_docs/README.md b/api_docs/README.md new file mode 100644 index 00000000..8def9053 --- /dev/null +++ b/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`). + +
+ +## **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`. + +
+ +## **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. + +
+ +## **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). diff --git a/api_docs/source/aerie_cli.rst b/api_docs/source/aerie_cli.rst new file mode 100644 index 00000000..de3e52ab --- /dev/null +++ b/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 \ No newline at end of file diff --git a/api_docs/source/aerie_cli.schemas.rst b/api_docs/source/aerie_cli.schemas.rst new file mode 100644 index 00000000..f1d3ab7f --- /dev/null +++ b/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: diff --git a/api_docs/source/aerie_cli.utils.rst b/api_docs/source/aerie_cli.utils.rst new file mode 100644 index 00000000..5dd4e9a8 --- /dev/null +++ b/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: diff --git a/api_docs/source/conf.py b/api_docs/source/conf.py new file mode 100644 index 00000000..2691b51d --- /dev/null +++ b/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'] diff --git a/api_docs/source/index.rst b/api_docs/source/index.rst new file mode 100644 index 00000000..db94e133 --- /dev/null +++ b/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 diff --git a/cli_docs/README.md b/cli_docs/README.md new file mode 100644 index 00000000..e3718ab2 --- /dev/null +++ b/cli_docs/README.md @@ -0,0 +1,39 @@ +# **Aerie-CLI Documentation** + +## **CLI Commands**: + +- [`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'`* + +
+ +### **Documentation for All Individual Commands** +Generate documentation for all Aerie-CLI commands using the `generate_cli_docs` script. + +Usage: + +```$ python3 generate_cli_docs.py``` \ No newline at end of file diff --git a/cli_docs/generate_cli_docs.py b/cli_docs/generate_cli_docs.py new file mode 100644 index 00000000..ab7869f9 --- /dev/null +++ b/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}") \ No newline at end of file