added /poller/gws/direct doc, started restructuring a bit

docs/source/protocol/index.rst

@@ -29,9 +29,10 @@ API modules
    :caption: Contents:
 
    classifier
-   poller
    lg
    data
    jobs
    msr
-   lnetd
+   lnetd
\ No newline at end of file
+
+.. automodule:: inventory_provider.routes.poller

docs/source/protocol/poller.rst

-.. poller endpoint docs
-
-
-BRIAN support Endpoints
-=========================
-
-These endpoints are intended for use by BRIAN.
-
-.. contents:: :local:
-
-/poller/interfaces</hostname>
----------------------------------
-
-.. autofunction:: inventory_provider.routes.poller.interfaces
-
-
-/poller/speeds</hostname>
----------------------------------
-
-.. autofunction:: inventory_provider.routes.poller.interface_speeds
-
-
-/poller/eumetsat-multicast
----------------------------------
-
-.. autofunction:: inventory_provider.routes.poller.eumetsat_multicast

inventory_provider/routes/poller.py

+"""
+BRIAN support Endpoints
+=========================
+
+These endpoints are intended for use by BRIAN.
+
+.. contents:: :local:
+
+/poller/interfaces</hostname>
+---------------------------------
+
+.. autofunction:: inventory_provider.routes.poller.interfaces
+
+
+/poller/speeds</hostname>
+---------------------------------
+
+.. autofunction:: inventory_provider.routes.poller.interface_speeds
+
+
+/poller/eumetsat-multicast
+---------------------------------
+
+.. autofunction:: inventory_provider.routes.poller.eumetsat_multicast
+
+
+/poller/gws/direct
+---------------------------------
+
+.. autofunction:: inventory_provider.routes.poller.gws_direct
+
+"""
 import json
 import logging
 import re
@@ -577,6 +609,23 @@ def eumetsat_multicast(hostname=None):
 @routes.route("/gws/direct", methods=['GET', 'POST'])
 @common.require_accepts_json
 def gws_direct():
+    """
+    Handler for `/poller/gws/direct` which returns required for polling
+     customer equipment counters for ISP connetions.
+
+    The response is a list of nren/isp/counter structures that must be
+    polled.
+
+    .. asjson::
+       inventory_provider.routes.poller.GWS_DIRECT_DATA_SCHEMA
+
+    This method returns essentially hard-coded data,
+    based on the information in POL1-422.
+
+    TODO: this hard-coded data should be in the config file
+
+    :return:
+    """
     data = [
       {
         "nren": "ARNES",