[Feature] Build docs for RTD

.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

sdk/.gitignore

@@ -1,2 +1,3 @@
 .env/
 target/
+_readthedocs/

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/

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

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'

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...

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`

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

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 = ['./']