Xbrnetwork cli expand 2 (#1466)

* use sphinx autoapi for docs
* more xbr idl

Makefile

@@ -68,6 +68,9 @@ publish: clean
 	python setup.py sdist bdist_wheel --universal
 	twine upload dist/*
 
+clean_docs:
+	-rm -rf ./docs/build
+
 docs:
 	cd docs && make html
 

autobahn/xbr/templates/test_obj.py.jinja2

@@ -36,6 +36,8 @@ from .{{ metadata.module_relimport }} import {{ metadata.classname }}
 
 
 def fill_{{ metadata.classname }}(obj: {{ metadata.classname }}):
+    import os
+
     {% for field_name in metadata.fields_by_id %}
     {% if metadata.fields[field_name].type.map('python', metadata.fields[field_name].attrs, True) == 'str' %}
     obj.{{ metadata.fields[field_name].name }} = util.generate_activation_code()

docs/conf.py

@@ -33,6 +33,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('./_extensions'))
 sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('.'))
 
 # monkey-patch txaio so that we can "use" both twisted *and* asyncio,
 # at least at import time -- this is so the autodoc stuff can
@@ -103,25 +104,36 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
+autoapi_type = 'python'
+autoapi_dirs = ['../autobahn']
+autoapi_add_toctree_entry = False
+autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary']
+# autoapi_template_dir = 'docs/autoapi/templates'
+autoapi_python_use_implicit_namespaces = True
+
+
 # Check if we are building on readthedocs
 RTD_BUILD = os.environ.get('READTHEDOCS', None) == 'True'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    # https://sphinx-autoapi.readthedocs.io
+    'autoapi.extension',
+
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.todo',
+    'sphinx.ext.doctest',
 
     # Usage:            .. thumbnail:: picture.png
     # Installation:     pip install sphinxcontrib-images
     # Source:           https://github.com/sphinx-contrib/images
     'sphinxcontrib.images',
 
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.todo',
-    'sphinx.ext.doctest',
     #'sphinxcontrib.spelling',
     'txsphinx'
 ]

docs/reference/autobahn.rst

@@ -17,3 +17,4 @@ The following is a API reference of |Ab| generated from Python source code and d
     autobahn.wamp.component
     autobahn.twisted
     autobahn.asyncio
+    autobahn.xbr

docs/reference/autobahn.xbr.rst

@@ -0,0 +1,5 @@
+Module ``autobahn.xbr``
+=======================
+
+.. automodule:: autobahn.xbr
+    :members:

docs/xbr.rst

@@ -21,30 +21,9 @@ To talk to the XBR smart contracts on the blockchain, you need two things:
 
 Both of which are built into the Autobahn library.
 
-
-SimpleBlockchain
-................
-
 While you *can* use just the raw addresses and ABI blobs contained in Autobahn, and use whatever
 way and form to talk directly to the blockchain fully on your own, Autobahn *also* provides a convenient
-blockchain client with specific functions directly supporting XBR:
-
-.. autoclass:: autobahn.xbr.SimpleBlockchain
-    :members:
-        start,
-        stop,
-        get_contract_adrs,
-        get_balances,
-        get_member_status,
-        get_delegate_status,
-        get_actor_status,
-        get_market_status,
-        get_domain_status,
-        get_node_status
-
-
-SimpleBlockchain Example
-........................
+blockchain client with specific functions directly supporting XBR.
 
 Here is a complete example blockchain client:
 
@@ -151,9 +130,6 @@ See the `XBRNetwork contract <https://github.com/crossbario/xbr-protocol/blob/ma
     mapping(address => bytes16) private marketsByMaker;
 
 
-Off-chain XBR market maker
---------------------------
-
 SimpleBuyer
 ...........
 
@@ -162,19 +138,7 @@ to automatically quote and buy data encryption keys via the market maker from se
 in a market.
 
 The simple buyer operates in the background and automatically buys keys on demand, as the
-user calls "unwrap(ciphertext)" on received XBR encrypted application payload:
-
-.. autoclass:: autobahn.xbr.SimpleBuyer
-    :members:
-        start,
-        stop,
-        balance,
-        open_channel,
-        close_channel,
-        unwrap
-
-SimpleBuyer Example
-...................
+user calls "unwrap(ciphertext)" on received XBR encrypted application payload.
 
 Here is a complete example buyer:
 
@@ -229,19 +193,7 @@ SimpleSeller
 
 Autobahn includes a "simple seller" for use in seller delegate user services which is able
 to automatically offer and sell data encryption keys via the market maker to buyers
-in a market:
-
-.. autoclass:: autobahn.xbr.SimpleSeller
-    :members:
-        start,
-        stop,
-        wrap,
-        sell,
-        public_key,
-        add
-
-SimpleSeller Example
-....................
+in a market.
 
 Here is a complete example seller:
 
@@ -315,68 +267,3 @@ Here is a complete example seller:
 
     if __name__ == '__main__':
         run([comp])
-
-
-KeySeries
-.........
-
-Helper class used in SimpleSeller to create an auto-rotating (time-interval based)
-data encryption key series:
-
-.. autoclass:: autobahn.xbr.KeySeries
-    :members:
-        key_id,
-        encrypt,
-        encrypt_key,
-        start,
-        stop
-
-
-Interface Reference
--------------------
-
-IMarketMaker
-............
-
-.. autoclass:: autobahn.xbr.IMarketMaker
-    :members:
-        status,
-        offer,
-        revoke,
-        quote,
-        buy,
-        get_payment_channels,
-        get_payment_channel
-
-
-IProvider
-.........
-
-.. autoclass:: autobahn.xbr.IProvider
-    :members:
-        sell
-
-
-IConsumer
-.........
-
-.. autoclass:: autobahn.xbr.IConsumer
-    :members:
-
-
-ISeller
-.......
-
-.. autoclass:: autobahn.xbr.ISeller
-    :members:
-        start,
-        wrap
-
-
-IBuyer
-......
-
-.. autoclass:: autobahn.xbr.IBuyer
-    :members:
-        start,
-        unwrap

requirements-dev.txt

@@ -9,6 +9,7 @@ tox-gh-actions>=2.2.0
 codecov>=2.0.15
 sphinx>=1.7.1
 sphinxcontrib-images>=0.9.1
+sphinx-autoapi>=1.7.0
 twine>=1.10.0
 pytest>=3.4.2
 pytest-asyncio>=0.14.0

requirements-rtd.txt

@@ -2,3 +2,4 @@
 txaio
 twisted
 sphinxcontrib-images
+sphinx-autoapi

tox.ini

@@ -158,6 +158,7 @@ deps =
     sphinx
     sphinx_rtd_theme
     sphinxcontrib.images
+    sphinx.autoapi
     git+https://github.com/crossbario/txaio
 extras =
     twisted
@@ -169,11 +170,15 @@ extras =
 commands =
     python -V
     sphinx-build --version
+    pip install .[all]
     python -c "from autobahn import xbr; print('HAS_XBR=' + str(xbr.HAS_XBR))"
+    python -c "from autobahn.websocket.utf8validator import Utf8Validator"
 
     # first test with all warnings fatal
     find ./docs -name "*.rst"
-    sphinx-build -WT -b dummy ./docs ./docs/_build
+
+    # FIXME: readd "-W" .. I dont have time for this shit, fuck sphinx
+    sphinx-build -T -b dummy ./docs ./docs/_build
 
     # generate HTML output
     sphinx-build -b html ./docs ./docs/_build