doc updates

README.md

@@ -1,11 +1,20 @@
 # axonius_api_client
 
-An API client for [Axonius](https://axonius.com).
+[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
+[![Made With Python](https://img.shields.io/badge/Made%20with-Python-1f425f.svg)](https://www.python.org/)
+[![PyPi package](https://badge.fury.io/py/axonius-api-client.svg)](https://pypi.org/project/axonius-api-client/)
+[![GitHub Repository](https://badge.fury.io/gh/Axonius%2Faxonius_api_client.svg)](https://github.com/Axonius/axonius_api_client)
+[![Documentation Status](https://readthedocs.org/projects/axonius-api-client/badge/?version=latest)](https://axonius-api-client.readthedocs.io/en/latest/?badge=latest)
+[![Downloads](https://pepy.tech/badge/axonius-api-client)](https://pepy.tech/project/axonius-api-client)
 
-## Documentation
+axonius-api-client is an API client for [Axonius](https://axonius.com) that provides:
 
-**With the 2.0 release the docs are in the midst of an overhaul.**
+* A fully modeled python API library that makes using the Axonius REST API easy.
+* A powerful command line interface that exposes most of the functionality of the
+  underlying python library.
 
-Current version of 2.0.1 has more docs with usage of the CLI.
+Resources:
 
-Found [here](https://axonius-api-client.readthedocs.io/en/latest/?)
+* [Documentation](https://axonius-api-client.readthedocs.io/)
+* [PyPi package listing](https://pypi.org/project/axonius-api-client/)
+* [GitHub repository](https://github.com/Axonius/axonius_api_client)

axonshell_manual.py

@@ -9,7 +9,7 @@
     import axonius_api_client as axonapi
 
     tools = axonapi.tools
-    axonapi.cli.context.load_dotenv()
+    axonapi.cli.cli_constants.load_dotenv()
 
     AX_URL = os.environ["AX_URL"]
     AX_KEY = os.environ["AX_KEY"]
@@ -29,5 +29,8 @@ def jdump(obj, **kwargs):
         log_console=True,
     )
 
-    with axonapi.cli.context.exc_wrap(wraperror=True):
-        ctx.start()
+    ctx.start()
+
+    devices = ctx.devices
+    users = ctx.users
+    adapters = ctx.adapters

docs/index.rst

@@ -1,36 +1,36 @@
 .. include:: /main/.special.rst
 
-|MIT license|
-|made-with-python|
-|code-black|
-|Downloads|
+|MIT license| |made-with-python| |PyPi| |github| |doc-status| |Downloads|
 
 Axonius API Client
 ##################################################################
 
-This is a python package that provides an API client for `Axonius`_.
+axonius-api-client is an API client for `Axonius`_. You can :doc:`Install it <main/install>` today!
+It provides:
 
-:doc:`Installation <main/install>` is simple using a number of methods.
+* A powerful :doc:`command line interface <main/usage_cli>` that exposes most of the
+  functionality of the underlying python library.
+* A fully modeled :doc:`python API library <main/usage_api>` that makes using
+  the Axonius REST API easy.
 
-Usage and examples are available for the :doc:`command line interface <main/usage_cli>` and the :doc:`Python API <main/usage_api>`.
+.. note::
+
+   This documentation is still in the midst of being re-worked to match the 2.0 release.
+   Additional usage examples and other updates should come just about every day.
 
 Table of Contents
 ###############################################
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
    :numbered:
 
    main/install.rst
    main/usage_cli.rst
    main/usage_api.rst
-   main/support.rst
+   main/contributing.rst
    main/releases.rst
 
-.. todo::
-
-   Finish API reference docstrings
-
 Indices and tables
 ###############################################
 
@@ -45,5 +45,12 @@ Indices and tables
    :target: https://lbesson.mit-license.org/
 .. |made-with-python| image:: https://img.shields.io/badge/Made%20with-Python-1f425f.svg
    :target: https://www.python.org/
-.. |code-black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
-   :target: https://github.com/python/black
+.. |PyPi| image:: https://badge.fury.io/py/axonius-api-client.svg
+   :target: https://pypi.org/project/axonius-api-client/
+   :alt: PyPi listing
+.. |github| image:: https://badge.fury.io/gh/Axonius%2Faxonius_api_client.svg
+   :target: https://github.com/Axonius/axonius_api_client
+   :alt: GitHub repository
+.. |doc-status| image:: https://readthedocs.org/projects/axonius-api-client/badge/?version=latest
+   :target: https://axonius-api-client.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status

docs/main/contributing.rst

@@ -0,0 +1,108 @@
+.. include:: /main/.special.rst
+
+Contribution
+###################################################
+
+We welcome all contributions to `axonius-api-client`.
+
+Support
+===================================================
+
+For any support requests, bug reports, or feature requests you can:
+
+* Open an issue in the `issue tracker`_
+* Send an email apiclient@axonius.com
+
+Reporting Issues
+===================================================
+
+When reporting issues, please include information for:
+
+- Python distribution and version
+- Operating System platform and version
+- `axonius-api-client` version
+- Full tracebacks of any exceptions
+
+Submitting Patches
+===================================================
+
+All patches should be submitted as pull requests on the `GitHub project`_.
+
+- Clearly explain what you're trying to accomplish.
+
+- Include tests for any changes.
+
+- Ensure the full :ref:`testing-suite` runs without any errors before submitting
+  a pull request.
+
+- Ensure the test coverage reports 100% before submitting a pull request.
+
+- Follow :pep:`8`.
+
+- Use `isort`_ and `black`_ to format your code and `flake8`_, `pydocstyle`_,
+  and `bandit`_ to lint your code:
+
+.. code-block:: shell
+
+    $ isort -rc -y axonius_api_client setup.py axonshell*.py
+    $ black axonius_api_client setup.py axonshell*.py
+    $ pydocstyle axonius_api_client setup.py axonshell*.py
+    $ flake8 --max-line-length 89 axonius_api_client setup.py axonshell*.py
+    $ bandit --skip B101 -r axonius_api_client
+
+.. _testing-suite:
+
+Testing Suite
+===================================================
+
+`axonius-api-client` uses `pytest`_ as it's test suite.
+
+To run all tests, create a .env file with the connection information:
+
+.. code-block:: shell
+
+    $ echo 'AX_URL=x' >> .env
+    $ echo 'AX_KEY=x' >> .env
+    $ echo 'AX_SECRET=x' >> .env
+
+Then run pytest to run the full test suite and generate test coverage in html format
+to `cov_html/index.html`:
+
+.. code-block:: shell
+
+    $ pytest \
+      -ra \
+      --verbose \
+      --cov-config=.coveragerc \
+      --cov-report=html:cov_html \
+      --cov=axonius_api_client \
+      --showlocals  \
+      --exitfirst \
+      axonius_api_client/tests
+
+Supported Python versions
+----------------------------------------------------------
+
+* Latest versions of 3.7 and 2.7
+* Windows, OSX, Linux
+
+Tested Python versions
+----------------------------------------------------------
+
+* 3.7.4 and 2.7.16 on OSX
+* 3.7.4 and 2.7.16 on Windows
+
+.. note::
+
+   As Python 2.7 is nearing it's end-of-life on 01/01/2020, 2.7 is not part of the
+   normal QA tests performed before releasing a new version. Please switch over to using
+   Python 3.7 as soon as possible!
+
+.. _issue tracker: https://github.com/Axonius/axonius_api_client/issues
+.. _GitHub project: https://github.com/Axonius/axonius_api_client
+.. _black: https://github.com/psf/black
+.. _flake8: https://gitlab.com/pycqa/flake8
+.. _pytest: https://docs.pytest.org/en/latest/
+.. _isort: https://github.com/timothycrosley/isort
+.. _pydocstyle: https://github.com/PyCQA/pydocstyle/
+.. _bandit: https://github.com/PyCQA/bandit

docs/main/install.rst

@@ -1,30 +1,54 @@
 .. include:: /main/.special.rst
 
+.. _installation:
+
 Installation
 #########################
 
-Using `pip`_
+Install Python
+============================================================
+
+Download and install the latest 3.7 version of `python`_ for your platform.
+
+If installing on Windows, make sure you check the option to add Python to the PATH.
+This will ensure that not only the `python` and `pip` binaries are on the path,
+but that the `axonshell` CLI script that comes with this package will be available on
+the PATH after you install it.
+
+.. note::
+
+   While 2.7 is supported, using it is not recommended due to the `pending EOL on January 1st 2020 <pyeol>`_.
+
+Install the package using `pip`_
 ============================================================
 
-   .. code-block:: console
+axonius-api-client is listed on `pypi`_, so you can do pip install from any
+platform that has python installed.
+
+.. code-block:: console
 
-      $ pip install axonius_api_client
+  $ pip install axonius_api_client
 
-Using `pipenv`_
+Install the package Using `pipenv`_
 ============================================================
 
-   .. code-block:: console
+pipenv makes it easy to create virtual environments for python projects.
 
-      $ pipenv install axonius_api_client
+.. code-block:: console
 
-Using `git`_
+  $ pipenv install axonius_api_client
+
+Download the entire repository using `git`_
 ============================================================
 
-   .. code-block:: console
+This is really only for those who wish to contribute to this project, although
+you can install the package after cloning the repository using ``python setup.py install``.
+
+.. code-block:: console
 
-      $ git clone git://github.com/Axonius/axonius_api_client.git
+  $ git clone git://github.com/Axonius/axonius_api_client.git
 
-From `GitHub`_
+Browse the repository on `GitHub`_
 ============================================================
 
 The master branch will always be the most recent stable version.
@@ -33,3 +57,6 @@ The master branch will always be the most recent stable version.
 .. _pipenv: https://pipenv.readthedocs.io/en/latest/
 .. _pip: https://pypi.org/project/pip/
 .. _GitHub: https://github.com/Axonius/axonius_api_client
+.. _pypi: https://pypi.org/project/axonius-api-client/
+.. _python: https://www.python.org/downloads/
+.. _pyeol: https://python3statement.org

docs/main/usage_api.rst

@@ -2,3 +2,73 @@
 
 API Usage
 ###############################################
+
+API Quickstart
+==============================================
+
+Install the package
+-----------------------------------------------
+
+.. code ::
+
+   $ pip install axonius-api-client
+
+See :ref:`Installation` for more details.
+
+Setup connection information
+----------------------------------------------
+
+.. code::
+
+    $ echo "AX_URL=x" >> .env
+    $ echo "AX_KEY=x" >> .env
+    $ echo "AX_SECRET=x" >> .env
+    $ chmod 600 .env
+
+See :ref:`connection_options` for more details.
+
+Establish a connection
+----------------------------------------------
+
+The axonius_api_client.connect.Connect object will connect to the Axonius instance and
+give you access to the API objects for devices, users, adapters, and enforcements:
+
+.. code:: python
+
+    import os
+
+    import axonius_api_client as axonapi
+
+    axonapi.cli.cli_constants.load_dotenv()
+
+    AX_URL = os.environ["AX_URL"]
+    AX_KEY = os.environ["AX_KEY"]
+    AX_SECRET = os.environ["AX_SECRET"]
+
+    ctx = axonapi.Connect(
+        url=AX_URL,
+        key=AX_KEY,
+        secret=AX_SECRET,
+    )
+
+    ctx.start()
+
+    devices = ctx.devices
+    users = ctx.users
+    adapters = ctx.adapters
+
+With the Connect object established, now you can use the API models.
+
+Here's a simple example to get a report of all device assets matching a query that
+shows all assets seen in the last 3 days. Also include the columns for AWS device type and OS Type:
+
+.. code:: python
+
+   query = '(specific_data.data.last_seen >= date("NOW - 3d"))'
+   fields = ["aws:aws_device_type", "os.type"]
+
+   assets = devices.get(query=query, fields=fields)
+
+.. todo::
+
+   The API reference docs are not done yet. The CLI usage docs will be finished first.