Publish docs to GH pages

.github/workflows/build-docs.yml

@@ -0,0 +1,46 @@
+name: Build and deploy sphinx docs
+
+on:
+  push:
+    branches: main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v3
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r requirements-dev.txt
+      - name: Build documentation
+        run: |
+          cd docs/
+          make html
+
+      - uses: actions/checkout@v4
+        with:
+          ref: "gh-pages"
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          path: "gh-pages-docs"
+
+      - name: Deploy to GitHub Pages
+        run: |
+          git config --global user.email "[email protected]"
+          git config --global user.name "GitHub Actions"
+          rm -rf ./gh-pages-docs/*
+          mv -f ${{ github.workspace }}/docs/_build/html/* ./gh-pages-docs
+          cd ./gh-pages-docs
+          touch .nojekyll
+          git add .
+          git commit -m "Deploy documentation from GitHub Actions" --allow-empty
+          git push origin gh-pages

.gitignore

@@ -139,3 +139,5 @@ typings/**
 !libbls.dll
 
 examples/output
+
+./docs/_build/*

README.md

@@ -2,6 +2,11 @@
 
 The Python SDK for interacting with MultiversX. It's an all in one sdk that can be used to create transactions (including smart contract calls and deployments), sign and broadcast transactions, create wallets and many more.
 
+## Documentation
+
+- [Cookbook](./examples/Cookbook.ipynb)
+- [Auto-generated documentation](https://multiversx.github.io/mx-sdk-py-incubator/)
+
 ## Development setup
 
 ### Virtual environment
@@ -40,3 +45,14 @@ If you want to skip network interaction tests run:
 ```
 pytest -m "not networkInteraction"
 ```
+
+### Regenerating the docs
+
+Each time a new module/submodule is added it needs to be added to the docs, as well. To do so `cd` in the root directory then run the following command:
+```bash
+sphinx-apidoc -f -o docs/ multiversx_sdk/ *_test.py *constants.py
+```
+
+This command will regenerate the `.rst` files for each module, excluding the tests and the `constants.py` files.
+
+Also, each time a new version is released, the [**conf.py**](/docs/conf.py) file should be updated accordingly.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,33 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+project = 'multiversx-sdk'
+copyright = '2024, MultiversX'
+author = 'MultiversX'
+release = '0.9.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.todo", "sphinx.ext.viewcode", "sphinx.ext.autodoc"]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+autoclass_content = 'both'

docs/index.rst

@@ -0,0 +1,20 @@
+.. multiversx-sdk documentation master file, created by
+   sphinx-quickstart on Wed Apr  3 14:19:32 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to multiversx-sdk's documentation!
+==========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/modules.rst

@@ -0,0 +1,7 @@
+multiversx_sdk
+==============
+
+.. toctree::
+   :maxdepth: 4
+
+   multiversx_sdk

docs/multiversx_sdk.core.adapters.rst

@@ -0,0 +1,21 @@
+multiversx\_sdk.core.adapters package
+=====================================
+
+Submodules
+----------
+
+multiversx\_sdk.core.adapters.query\_runner\_adapter module
+-----------------------------------------------------------
+
+.. automodule:: multiversx_sdk.core.adapters.query_runner_adapter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: multiversx_sdk.core.adapters
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/multiversx_sdk.core.proto.rst

@@ -0,0 +1,29 @@
+multiversx\_sdk.core.proto package
+==================================
+
+Submodules
+----------
+
+multiversx\_sdk.core.proto.transaction\_pb2 module
+--------------------------------------------------
+
+.. automodule:: multiversx_sdk.core.proto.transaction_pb2
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+multiversx\_sdk.core.proto.transaction\_serializer module
+---------------------------------------------------------
+
+.. automodule:: multiversx_sdk.core.proto.transaction_serializer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: multiversx_sdk.core.proto
+   :members:
+   :undoc-members:
+   :show-inheritance: