feat: add documentation site (#115)

[ci skip]

Author: branchvincent

.github/workflows/docs.yaml

@@ -0,0 +1,28 @@
+name: Documentation
+
+on:
+  workflow_dispatch:
+  release:
+    types: [released]
+
+jobs:
+  docs:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - run: pip install poetry
+      - name: Set up cache
+        uses: actions/cache@v2
+        with:
+          path: .venv
+          key: ${{ runner.os }}-venv-py3.8-${{ hashFiles('**/poetry.lock') }}
+      - name: Install package
+        run: poetry install
+      - name: Publish documentation
+        run: poetry run mkdocs gh-deploy

README.md

@@ -18,8 +18,7 @@ contxt --help
 
 ## Documentation
 
-- [CLI](docs/cli.md)
-- [Worker](docs/worker.md)
+Please refer to <https://ndustrialio.github.io/contxt-sdk-python>.
 
 ## Contributing
 

contxt/cli/commands/auth.py

@@ -26,6 +26,6 @@ def logout(client: Clients) -> None:
 @click.argument("audience")
 @click.pass_obj
 def token(client: Clients, audience: str) -> None:
-    """Fetch token for an API."""
+    """Fetch an access token for an API."""
     token = client.auth.get_token_provider(audience).access_token
     print(token)

contxt/cli/main.py

@@ -24,7 +24,7 @@ def get_command(self, ctx, name):
         return ns[name]
 
 
-@click.group(cls=Cli, context_settings=dict(help_option_names=["-h", "--help"]))
+@click.group(cls=Cli, name="contxt", context_settings=dict(help_option_names=["-h", "--help"]))
 @click.option(
     "--env",
     type=click.Choice(["production", "staging"]),

docs/cli.md

@@ -0,0 +1,4 @@
+::: mkdocs-click
+    :module: contxt.__main__
+    :command: cli
+    :prog_name: contxt

docs/cli/commands.md

@@ -0,0 +1,27 @@
+# Quickstart
+
+## Login
+
+To access any Contxt API, first login with your Contxt credentials:
+
+```sh
+contxt auth login
+```
+
+This will open a browser window, ask you to login (if not already), and confirm a code. If this succeeds, you should see something like `Your device is now connected.`
+
+## Usage
+
+The CLI's general usage pattern is:
+
+```sh
+contxt [entity] [action]
+```
+
+For example, to _get_ all _orgs_:
+
+```sh
+contxt orgs get
+```
+
+See all supported commands [here](./commands.md).

docs/cli/index.md

@@ -0,0 +1,40 @@
+# Overview
+
+This software development kit (SDK) gives you quick access to the set of Contxt API's from <https://ndustrial.io>, both programatically and on the command line.
+
+## Install
+
+Before proceeding, you must have [Python](https://www.python.org/) 3.7+ installed.
+
+### Library
+
+To install and use this SDK as a library, just use [pip](https://pip.pypa.io/en/stable/quickstart/):
+
+```sh
+python3 -m pip install --upgrade contxt-sdk
+```
+
+### CLI
+
+If you only need the CLI, the above method will work fine. However, we recommend using [pipx](https://pipxproject.github.io/pipx/installation/#install-pipx)[^1]:
+
+```sh
+# Setup pipx (once only)
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+
+# Install
+pipx install contxt-sdk
+
+# Upgrade
+pipx upgrade contxt-sdk
+```
+
+Run the following to ensure the installation was successful:
+
+```sh
+$ contxt --version
+contxt, version 2.1.4
+```
+
+[^1]: Why pipx? See [here](https://pipxproject.github.io/pipx/#how-is-it-different-from-pip)

docs/examples/worker.py

@@ -10,4 +10,24 @@ Within Contxt, a machine client is identified by a unique client id and secret p
 
 Our SDK provides a `BaseWorker` class to help abstract the authentication process between a machine client and a Contxt API. Upon instantation, the class will look for your machine credientials in the environment variables `CLIENT_ID` and `CLIENT_SECRET`, and then store this pair as the attribute `auth`. Next, your worker's business logic is defined in the `do_work()` method. If we need to make requests to a Contxt API here, we simply inject our credentials when instantiating the service class (i.e. `FacilitiesService(self.auth)`). Now, that class handles generating, sending, and refreshing your JWT to authenticate requests to that API.
 
-For a more concrete example, see [worker.py](examples/worker.py).
+For a more concrete example:
+
+```python
+from contxt.services.facilities import FacilitiesService
+from contxt.workers import BaseWorker
+
+
+class ExampleWorker(BaseWorker):
+    def __init__(self):
+        super().__init__()
+        self.facilities_service = FacilitiesService(self.auth)
+
+    def do_work(self):
+        facilities = self.facilities_service.get_facilities()
+        print(facilities)
+
+
+if __name__ == "__main__":
+    worker = ExampleWorker()
+    worker.do_work()
+```

docs/index.md

@@ -0,0 +1,8 @@
+site_name: Contxt SDK
+theme: readthedocs
+repo_url: https://github.com/ndustrialio/contxt-sdk-python/
+markdown_extensions:
+  - footnotes
+  - mkdocs-click
+  - toc:
+      permalink: True