From c987581b17111222efb7bc1f88a17c5707e90d6a Mon Sep 17 00:00:00 2001 From: Roman Proskuryakov Date: Mon, 4 Dec 2023 20:30:45 +0300 Subject: [PATCH] Build docs for RDT --- .github/workflows/sdk.yml | 16 ++++--- sdk/.gitignore | 1 + sdk/.readthedocs.yaml | 12 +++++ sdk/docs/requirements.txt | 9 ++++ sdk/docs/source/conf.py | 90 ++++++++++++++++++++++++++++++++++++ sdk/docs/source/examples.rst | 71 ++++++++++++++++++++++++++++ sdk/docs/source/index.rst | 25 ++++++++++ sdk/docs/source/usage.rst | 9 ++++ sdk/pyproject.toml | 1 + 9 files changed, 228 insertions(+), 6 deletions(-) create mode 100644 sdk/.readthedocs.yaml create mode 100644 sdk/docs/requirements.txt create mode 100644 sdk/docs/source/conf.py create mode 100644 sdk/docs/source/examples.rst create mode 100644 sdk/docs/source/index.rst create mode 100644 sdk/docs/source/usage.rst diff --git a/.github/workflows/sdk.yml b/.github/workflows/sdk.yml index f677dab..1dc6019 100644 --- a/.github/workflows/sdk.yml +++ b/.github/workflows/sdk.yml @@ -4,7 +4,7 @@ on: workflow_call: jobs: - sdk_check: + check: name: Check runs-on: ubuntu-latest defaults: @@ -22,9 +22,9 @@ jobs: github_token: ${{ secrets.GITHUB_TOKEN }} workdir: ./sdk fail_on_error: true - sdk_test: + build_test: name: Build & Test - needs: [sdk_check] + needs: [check] runs-on: ubuntu-latest defaults: run: @@ -40,9 +40,13 @@ jobs: with: args: --release --features openssl/vendored working-directory: ./sdk + - name: Install Wheel + run: pip install target/wheels/*.whl + - name: Build & Test RTD + run: | + pip install -r docs/requirements.txt + sphinx-build docs/source/ _readthedocs/ + sphinx-build -b doctest docs/source/ _readthedocs/doctest - name: Test run: | - python -m venv .env - source .env/bin/activate - maturin develop --release --features openssl/vendored python test.py diff --git a/sdk/.gitignore b/sdk/.gitignore index 366fea7..68947d4 100644 --- a/sdk/.gitignore +++ b/sdk/.gitignore @@ -1,2 +1,3 @@ .env/ target/ +_readthedocs/ diff --git a/sdk/.readthedocs.yaml b/sdk/.readthedocs.yaml new file mode 100644 index 0000000..70f34bf --- /dev/null +++ b/sdk/.readthedocs.yaml @@ -0,0 +1,12 @@ +version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.11" + rust: "1.70" + commands: + - pip install maturin[patchelf] + - cd sdk && maturin build + - pip install sdk/target/wheels/*.whl + - pip install -r sdk/docs/requirements.txt + - sphinx-build -M html sdk/docs/source/ _readthedocs/ diff --git a/sdk/docs/requirements.txt b/sdk/docs/requirements.txt new file mode 100644 index 0000000..b3ec689 --- /dev/null +++ b/sdk/docs/requirements.txt @@ -0,0 +1,9 @@ +sphinx-autoapi==3.0.0 +sphinx-rtd-theme==2.0.0 +sphinxcontrib-applehelp==1.0.4 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==2.0.1 +sphinxcontrib-jquery==4.1 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.5 diff --git a/sdk/docs/source/conf.py b/sdk/docs/source/conf.py new file mode 100644 index 0000000..ad3d11e --- /dev/null +++ b/sdk/docs/source/conf.py @@ -0,0 +1,90 @@ +# Configuration file for the Sphinx documentation builder. + + +# We need to import the module to get __doc__ strings in runtime. +import aleo + + +# -- Project information + +project = 'aleo' +copyright = '2023, AleoHQ' +author = 'kpp' + +version = '0.2.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'autoapi.extension', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None) +} + +autoapi_dirs = ['../../'] +autoapi_file_patterns = ['aleo.pyi'] +autoapi_generate_api_docs = True +autoapi_add_toctree_entry = False +autoapi_keep_files = False + +autoapi_options = [ + "members", + "undoc-members", + "show-inheritance", + "show-module-summary", + "imported-members", +] + +autodoc_typehints = "signature" + +# We need to use autoapi because autodoc +# doesn' twork with stub files. +# +# However when we use stub files, autodoc doesn't +# know anything about __doc__ string from the .so library. +# +# So we need to monkey patch the autoapi objects to update +# its obj._docstring to aleo.so.__doc__. +def monkey_patch_documentation(app, what, name, obj, skip, options): + def transform_docstring(doc): + if doc: + return doc.replace("\n", " ") + "\n" + else: + return '' + + if name.startswith("aleo"): + if what == "module": + doc = aleo.__doc__ + obj._docstring = transform_docstring(doc) + if what == "class": + (module, klass) = name.split(".") + klass = getattr(aleo, klass) + doc = klass.__doc__ + obj._docstring = transform_docstring(doc) + if what == "method": + (module, klass, method_name) = name.split(".") + klass = getattr(aleo, klass) + method = getattr(klass, method_name) + if method_name == "from_bytes": + obj.args = "bytes: bytes" + doc = method.__doc__ + obj._docstring = transform_docstring(doc) + if what == "property": + (module, klass, property_name) = name.split(".") + klass = getattr(aleo, klass) + property = getattr(klass, property_name) + doc = property.__doc__ + obj._docstring = transform_docstring(doc) + return None + +def setup(sphinx): + sphinx.connect("autoapi-skip-member", monkey_patch_documentation) + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' diff --git a/sdk/docs/source/examples.rst b/sdk/docs/source/examples.rst new file mode 100644 index 0000000..bd83b02 --- /dev/null +++ b/sdk/docs/source/examples.rst @@ -0,0 +1,71 @@ +Examples +================= + +.. testsetup:: * + + import aleo + +Working with accounts +********************* + +.. doctest:: + + >>> account = aleo.Account() + >>> private_key = account.private_key() + >>> secret = str(private_key) + >>> restored = aleo.PrivateKey.from_string(secret) + >>> same_account = aleo.Account.from_private_key(private_key) + >>> assert account == same_account + + +Working with signatures +*********************** + +.. doctest:: + + >>> account = aleo.Account() + >>> message = b'Hello world' + >>> signature = account.sign(message) + >>> serialized = str(signature) + >>> restored = aleo.Signature.from_string(serialized) + >>> assert account.verify(restored, message) + + +Calling a **transfer_public** function +************************************** + +.. doctest:: + :options: +ELLIPSIS + + >>> private_key = aleo.PrivateKey() + >>> destination = aleo.Account().address() + >>> amount = aleo.Credits(0.3) + >>> query = aleo.Query.rest("https://explorer.hamp.app") + >>> process = aleo.Process.load() + >>> credits = aleo.Program.credits() + >>> process.add_program(credits) + >>> transfer_name = aleo.Identifier.from_string("transfer_public") + >>> transfer_auth = process.authorize(private_key, credits.id(), transfer_name, [ + ... aleo.Value.from_literal(aleo.Literal.from_address(destination)), + ... aleo.Value.from_literal(aleo.Literal.from_u64( + ... aleo.U64(int(amount.micro())))), + ... ]) + >>> (_transfer_resp, transfer_trace) = process.execute(transfer_auth) + >>> transfer_trace.prepare(query) + >>> transfer_execution = transfer_trace.prove_execution( + ... aleo.Locator(credits.id(), aleo.Identifier.from_string("transfer"))) + >>> execution_id = transfer_execution.execution_id() + >>> process.verify_execution(transfer_execution) + + >>> (fee_cost, _) = process.execution_cost(transfer_execution) + >>> fee_priority = None + >>> fee_auth = process.authorize_fee_public( + ... private_key, fee_cost, execution_id, fee_priority) + >>> (_fee_resp, fee_trace) = process.execute(fee_auth) + >>> fee_trace.prepare(query) + >>> fee = fee_trace.prove_fee() + >>> process.verify_fee(fee, execution_id) + + >>> transaction = aleo.Transaction.from_execution(transfer_execution, fee) + >>> transaction.to_json() + '{"type":"execute","id":"at... diff --git a/sdk/docs/source/index.rst b/sdk/docs/source/index.rst new file mode 100644 index 0000000..e59cf15 --- /dev/null +++ b/sdk/docs/source/index.rst @@ -0,0 +1,25 @@ +Welcome to Aleo's documentation! +=================================== + +**aleo** is a Python SDK for the https://aleo.org/ project. + +.. note:: + + This project is under active development. + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + usage + examples + autoapi/aleo/index + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/sdk/docs/source/usage.rst b/sdk/docs/source/usage.rst new file mode 100644 index 0000000..b9f8e83 --- /dev/null +++ b/sdk/docs/source/usage.rst @@ -0,0 +1,9 @@ + +Installation +------------ + +To use Aleo SDK, first install it using pip: + +.. code-block:: console + + (.venv) $ pip install aleo diff --git a/sdk/pyproject.toml b/sdk/pyproject.toml index 1de9300..0533d47 100644 --- a/sdk/pyproject.toml +++ b/sdk/pyproject.toml @@ -12,4 +12,5 @@ authors = ["Konstantin Pandl", "Mike Turner", "Roman Proskuryakov"] [tool.pyright] reportMissingModuleSource = false # don't report missing aleo.so for CI purposes +ignore = ['./docs'] strict = ['./']