updated documents

631d2eeb · Erik Reid · f7143983 · 631d2eeb · 631d2eeb · f7143983
Commit 631d2eeb authored 2 years ago by Erik Reid
--- a/docs/dump-openapi-spec.py
+++ b/docs/dump-openapi-spec.py
@@ -9,14 +9,17 @@ config_filename = os.path.join(
    os.path.dirname(__file__),
    '..', 'config-example.json')
+output_filename = os.path.join(
+    os.path.dirname(__file__),
+    'source', '_static', 'openapi.json')
 os.environ['SETTINGS_FILENAME'] = config_filename
 app = resource_management.create_app()
 client = TestClient(app)
 rsp = client.get('/openapi.json')
 openapi_doc = json.dumps(rsp.json(), indent=2)
-if len(sys.argv) > 1 and sys.argv[1]:
+with open(output_filename, 'w') as f:
-    with open(sys.argv[1], 'w') as output:
+  f.write(openapi_doc)
-        output.write(openapi_doc)
-else:
+print(f'wrote {output_filename}')
-    print(openapi_doc)
--- a/docs/source/_static/openapi.html
+++ b/docs/source/_static/openapi.html
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta
+    name="description"
+    content="SwaggerUI"
+  />
+  <title>SwaggerUI</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
+<script>
+  window.onload = () => {
+    window.ui = SwaggerUIBundle({
+      url: '_static/openapi.json',
+      dom_id: '#swagger-ui',
+    });
+  };
+</script>
+</body>
+</html>
\ No newline at end of file
--- a/docs/source/basic-tools.rst
+++ b/docs/source/basic-tools.rst
-.. list of basic cli tools
-CLI Tools
-=========================
-.. automodule:: resource_management.cli
-.. automodule:: resource_management.hardware.juniper
--- a/docs/source/images/db-er.png
+++ b/docs/source/images/db-er.png
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,43 +6,15 @@
 NAT Resource Management
 ==========================
-Documentation for the NAT Resource Management tools
+Documentation for the NAT Resource Management service
------------------
-Configuration file format
---------------------------------
-The following example indicates the schema for the configuration file required to call the Resource Management client::
-   {
-         "mysql":{
-                  "username":"mydbuser",
-                  "password":"mydbpass",
-                  "hostname":"localhost",
-                  "dbname":"mydb"
-         },
-         "ssh":{
-                  "username":"user",
-                  "password":"pass",
-                  "private-key":"/path/to/private/key"
-                  "ssh-config":"/path/to/ssh-config"
-         }
-   }
-All "mysql" parameters are mandatory. For "ssh", username is mandatory, and either password or private-key must be provided. ssh-config is optional.
-Excuting the client
---------------------
-To create a new router from its fqdn::
-   python3 cli.py create  --config /path/to/resource_management_config.json --fqdn test.example.com
 .. toctree::
   :maxdepth: 1
   :caption: Contents:
-   basic-tools
+   quickstart
   db
+`Swagger API Docs <_static/openapi.html>`__
--- a/docs/source/quickstart.rst
+++ b/docs/source/quickstart.rst
+.. db model intro & info
+Quick Start
+==================
+*This is a quick setup guide for running
+standalone on your local machine*
+Create a Local Database
+--------------------------
+* set the value of `sqlalchemy.url`
+  in `alembic.ini` to point to a writeable file, e.g.
+  .. code-block:: python
+     sqlalchemy.url = sqlite:////absolute/path/to/foo.db
+* create the database by running the alembic
+  migration from the module (`resource_management`) directory
+  .. code-block:: bash
+     alembic upgrade head
+Running the App
+-------------------
+* create a settings filename
+  (see `config-example.json` for an example) ... something like:
+  .. code-block:: json
+     {
+       "db": "sqlite:////tmp/test.db",
+       "ssh": {
+         "username": "ro-username",
+         "private-key": "/absolute/path/to/private/key"
+       }
+    }
+* run the app like this
+  (`app.py` starts the server on port 44444):
+  .. code-block:: bash
+     SETTINGS_FILENAME=/absolute/path/to/config.json python -m resource_management.app
+Examples
+* get the version
+  .. code-block:: bash
+     curl http://localhost:44444/api/version
+* load interfaces from a router
+  .. code-block:: bash
+     curl -X POST http://localhost:44444/api/initialize-router/router.host.name
+* view the docs by loading `http://localhost:44444/docs`
+  in your browser (there are requests for reserving
+  lags and physical lag interfaces)
--- a/tox.ini
+++ b/tox.ini
@@ -18,4 +18,9 @@ commands =
    coverage html
    coverage report --fail-under 80
    flake8
+    python docs/dump-openapi-spec.py
+    # to render the diagrams:
+    #   pip install -r docs/requirements-er.txt
+    #   ... and install dot on the system
+    # python docs/render_db_diagrams.py
    sphinx-build -M html docs/source docs/build