fixing client docstrings. plugin documentation expanded.

amqtt/client.py

@@ -176,7 +176,7 @@ class MQTTClient:
             [CONNACK](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718033)'s return code
 
         Raises:
-            `amqtt.client.ConnectException` if connection fails
+            amqtt.client.ConnectException: if connection fails
         """
         additional_headers = additional_headers if additional_headers is not None else {}
         self.session = self._init_session(uri, cleansession, cafile, capath, cadata)
@@ -240,7 +240,7 @@ class MQTTClient:
             [CONNACK](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718033) return code
 
         Raises:
-            `amqtt.client.ConnectException` if re-connection fails after max retries.
+            amqtt.client.ConnectException: if re-connection fails after max retries.
         """
         if self.session and self.session.transitions.is_connected():
             self.logger.warning("Client already connected")
@@ -404,7 +404,7 @@ class MQTTClient:
             instance of `amqtt.session.ApplicationMessage` containing received message information flow.
 
         Raises:
-            `asyncio.TimeoutError` if timeout occurs before a message is delivered
+            asyncio.TimeoutError: if timeout occurs before a message is delivered
         """
         if self._handler is None:
             msg = "Handler is not initialized."

docs/plugins.md

@@ -1,4 +1,47 @@
-# Plugin: $SYS
+# Existing Plugins
+
+## Plugin: Anonymous Authentication
+
+plugin which allows clients to connect without credentials
+
+### Config Options
+
+```yaml
+
+auth:
+  allow-anonymous: true # or false
+
+```
+
+## Plugin: Password Authentication from File
+
+clients are authorized by providing username and password, compared against file
+
+### Config Options
+
+```yaml
+
+auth:
+  password-file: /path/to/password_file
+
+```
+
+### File Format
+
+  
+The file includes `username:password` pairs, one per line.
+
+The password should be encoded using sha-512 with `mkpasswd -m sha-512` or:
+
+```python
+import sys
+from getpass import getpass
+from passlib.hash import sha512_crypt
+
+passwd = input() if not sys.stdin.isatty() else getpass()
+print(sha512_crypt.hash(passwd))
+```
+## Plugin: $SYS
 
 Publishes, on a periodic basis, statistics about the broker
 
@@ -12,9 +55,9 @@ Publishes, on a periodic basis, statistics about the broker
 - `$SYS/broker/load/bytes/sent` - payload: 'data` - payload: `data`,  int
 - `$SYS/broker/messages/received` - payload: `data`, int
 - `$SYS/broker/messages/sent` - payload: `data`, int
-- `$SYS/broker/time` - payload: `data`,  int (current, epoch seconds)
-- `$SYS/broker/uptime` - payload: `data`,  datetime (start)
-- `$SYS/broker/uptime/formatted` - payload: `data`, int (seconds)
+- `$SYS/broker/time` - payload: `data`,  int (current time, epoch seconds)
+- `$SYS/broker/uptime` - payload: `data`, int (seconds since broker start)
+- `$SYS/broker/uptime/formatted` - payload: `data`, datetime (start time of broker in UTC)
 - `$SYS/broker/clients/connected` - payload: `data`, int
 - `$SYS/broker/clients/disconnected` - payload: `data`, int
 - `$SYS/broker/clients/maximum` - payload: `data`, int

docs/references/common.md

@@ -1,6 +1,6 @@
 # Common API
 
-This document describes `aMQTT` common API both used by [MQTT Client](mqttclient.md) and [Broker](broker.md).
+This document describes `aMQTT` common API both used by [MQTT Client](client.md) and [Broker](broker.md).
 
 ## Reference
 

docs/references/index.md

@@ -1,15 +0,0 @@
-# References
-
-Reference documentation for aMQTT console scripts and programming API.
-
-## Console scripts
-
-- [amqtt_pub](amqtt_pub.md): MQTT client for publishing messages to a broker
-- [amqtt_sub](amqtt_sub.md): MQTT client for subscribing to topics and retrieved published messages
-- [amqtt](amqtt.md): Autonomous MQTT broker
-
-## Programming API
-
-- [mqttclient](mqttclient.md): MQTT client API reference
-- [broker](broker.md): MQTT broker API reference
-- [common](common.md): Common API

mkdocs.yml

@@ -17,17 +17,21 @@ nav:
   - Home:
       - Overview: index.md
       - Quickstart: quickstart.md
-      - CLI Usage:
+      - Console scripts:
           - Broker: references/amqtt.md
           - Publisher: references/amqtt_pub.md
           - Subscriber: references/amqtt_sub.md
-      - API Usage:
+      - Programming API:
           - Broker: references/broker.md
           - Client: references/client.md
+          - Common: references/common.md
       - Plugins:
-          - $SYS: plugins/sys_broker.md
+          - Existing: plugins.md
+          - Custom: custom.md
       - Reference:
           - Contributing: contributing.md
+          - Change log: changelog.md
+          - Coverage: coverage.md
           - Code of Conduct: code_of_conduct.md
           - Security: security.md
           - License: license.md