From 87ae2be40414da4e194685078b22825107d6d6cd Mon Sep 17 00:00:00 2001 From: Tobias Oberstein Date: Fri, 26 Feb 2021 02:36:22 +0100 Subject: [PATCH] Xbrnetwork cli expand 2 (#1466) * use sphinx autoapi for docs * more xbr idl --- Makefile | 3 + autobahn/xbr/templates/test_obj.py.jinja2 | 2 + docs/conf.py | 18 +++- docs/reference/autobahn.rst | 1 + docs/reference/autobahn.xbr.rst | 5 + docs/xbr.rst | 119 +--------------------- requirements-dev.txt | 1 + requirements-rtd.txt | 1 + tox.ini | 7 +- 9 files changed, 37 insertions(+), 120 deletions(-) create mode 100644 docs/reference/autobahn.xbr.rst diff --git a/Makefile b/Makefile index d1265bc74..e6525bfdf 100755 --- a/Makefile +++ b/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 diff --git a/autobahn/xbr/templates/test_obj.py.jinja2 b/autobahn/xbr/templates/test_obj.py.jinja2 index e9a76b051..5899585ca 100644 --- a/autobahn/xbr/templates/test_obj.py.jinja2 +++ b/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() diff --git a/docs/conf.py b/docs/conf.py index c6548d1bd..5ebc6168e 100644 --- a/docs/conf.py +++ b/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,6 +104,14 @@ 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' @@ -110,18 +119,21 @@ def autodoc_skip_member(app, what, name, obj, skip, options): # 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' ] diff --git a/docs/reference/autobahn.rst b/docs/reference/autobahn.rst index 57fd58aae..e1da6e696 100644 --- a/docs/reference/autobahn.rst +++ b/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 diff --git a/docs/reference/autobahn.xbr.rst b/docs/reference/autobahn.xbr.rst new file mode 100644 index 000000000..70b7a7511 --- /dev/null +++ b/docs/reference/autobahn.xbr.rst @@ -0,0 +1,5 @@ +Module ``autobahn.xbr`` +======================= + +.. automodule:: autobahn.xbr + :members: diff --git a/docs/xbr.rst b/docs/xbr.rst index 228a17313..72a4d4849 100644 --- a/docs/xbr.rst +++ b/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 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 diff --git a/requirements-dev.txt b/requirements-dev.txt index 8f98b7ef4..8f49e0666 100644 --- a/requirements-dev.txt +++ b/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 diff --git a/requirements-rtd.txt b/requirements-rtd.txt index bfdad3887..fd546f87f 100644 --- a/requirements-rtd.txt +++ b/requirements-rtd.txt @@ -2,3 +2,4 @@ txaio twisted sphinxcontrib-images +sphinx-autoapi diff --git a/tox.ini b/tox.ini index 878eb5664..2ebd9a0e8 100644 --- a/tox.ini +++ b/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