docs: generate deltachat-rpc-client documentation

To preview the docs, run:
```
scripts/build-python-docs.sh
firefox dist/html/index.html
```

I have removed the Makefile because modern Sphinx Makefile is just a
wrapper for `sphinx-build -M`:
3596590317/sphinx/templates/quickstart/Makefile.new_t
and sphinx-quickstart even has an option `--no-makefile`.
`make.bat` makes even less sense.
In `scripts/build-python-docs.sh` I use `sphinx-build` directly
without `make` wrapper.
This commit is contained in:
link2xt
2023-11-20 00:06:33 +00:00
parent d3c221e061
commit 30f8522626
32 changed files with 472 additions and 810 deletions

View File

@@ -0,0 +1,68 @@
===========
Development
===========
To develop JSON-RPC bindings,
clone the `deltachat-core-rust <https://github.com/deltachat/deltachat-core-rust/>`_ repository::
git clone https://github.com/deltachat/deltachat-core-rust.git
Testing
=======
To run online tests, set ``CHATMAIL_DOMAIN``
to a domain of the email server
that can be used to create testing accounts::
export CHATMAIL_DOMAIN=nine.testrun.org
Then run ``scripts/run-rpc-test.sh``
to build debug version of ``deltachat-rpc-server``
and run ``deltachat-rpc-client`` tests
in a separate virtual environment managed by `tox <https://tox.wiki/>`_.
Development Environment
=======================
Creating a new virtual environment
to run the tests each time
as ``scripts/run-rpc-test.sh`` does is slow
if you are changing the tests or the code
and want to rerun the tests each time.
If you are developing the tests,
it is better to create a persistent virtual environment.
You can do this by running ``scripts/make-rpc-testenv.sh``.
This creates a virtual environment ``venv`` which you can then enter with::
. venv/bin/activate
Then you can run the tests with
::
pytest deltachat-rpc-client/tests/
Refer to `pytest documentation <https://docs.pytest.org/>` for details.
If make the changes to Delta Chat core
or Python bindings, you can rebuild the environment by rerunning
``scripts/make-rpc-testenv.sh``.
It is ok to rebuild the activated environment this way,
you do not need to deactivate or reactivate the environment each time.
Using REPL
==========
Once you have a development environment,
you can quickly test things in REPL::
$ python
>>> from deltachat_rpc_client import *
>>> rpc = Rpc()
>>> rpc.start()
>>> dc = DeltaChat(rpc)
>>> system_info = dc.get_system_info()
>>> system_info["level"]
'awesome'
>>> rpc.close()

View File

@@ -0,0 +1,19 @@
Examples
========
Echo bot
--------
.. include:: ../../../deltachat-rpc-client/examples/echobot_no_hooks.py
:literal:
Echo bot with hooks
-------------------
.. include:: ../../../deltachat-rpc-client/examples/echobot.py
:literal:
Advanced echo bot
-----------------
.. include:: ../../../deltachat-rpc-client/examples/echobot_advanced.py
:literal:

View File

@@ -0,0 +1,36 @@
Install
=======
To use JSON-RPC bindings for Delta Chat core you will need
a ``deltachat-rpc-server`` binary which provides Delta Chat core API over JSON-RPC
and a ``deltachat-rpc-client`` Python package which is a JSON-RPC client that starts ``deltachat-rpc-server`` process and uses JSON-RPC API.
`Create a virtual environment <https://docs.python.org/3/library/venv.html>`__ if you
dont have one already and activate it::
$ python -m venv venv
$ . venv/bin/activate
Install ``deltachat-rpc-server``
--------------------------------
To get ``deltachat-rpc-server`` binary you have three options:
1. Install ``deltachat-rpc-server`` from PyPI using ``pip install deltachat-rpc-server``.
2. Build and install ``deltachat-rpc-server`` from source with ``cargo install --git https://github.com/deltachat/deltachat-core-rust/ deltachat-rpc-server``.
3. Download prebuilt release from https://github.com/deltachat/deltachat-core-rust/releases and install it into ``PATH``.
Check that ``deltachat-rpc-server`` is installed and can run::
$ deltachat-rpc-server --version
1.131.4
Then install ``deltachat-rpc-client`` with ``pip install deltachat-rpc-client``.
Install ``deltachat-rpc-client``
--------------------------------
To get ``deltachat-rpc-client`` Python library you can:
1. Install ``deltachat-rpc-client`` from PyPI using ``pip install deltachat-rpc-client``.
2. Install ``deltachat-rpc-client`` from source with ``pip install git+https://github.com/deltachat/deltachat-core-rust.git@main#subdirectory=deltachat-rpc-client``.

View File

@@ -0,0 +1,8 @@
Introduction
============
JSON-RPC bindings are available via the `deltachat-rpc-client <https://pypi.org/project/deltachat-rpc-client/>`_ Python package.
This package provides only the Python bindings and requires ``deltachat-rpc-server`` binary to be installed.
`deltachat-rpc-server <https://pypi.org/project/deltachat-rpc-server/>`_ package provides ``deltachat-rpc-server`` binary for Linux, Windows, macOS and Android.
RPC client connects to standalone Delta Chat RPC server ``deltachat-rpc-server`` and provides Python interface to it.

View File

@@ -0,0 +1,5 @@
API Reference
=============
.. automodule:: deltachat_rpc_client
:members: