various improvements

docs/source/_static/custom.css

@@ -0,0 +1 @@
+div.code-block-caption {background: #d0d0d0;}

docs/source/cli/index.rst

@@ -0,0 +1,8 @@
+CLI
+===
+
+.. toctree::
+    :maxdepth: 1
+
+    usage
+    reference

docs/source/cli/reference.rst

@@ -0,0 +1,7 @@
+CLI Reference
+=============
+
+.. argparse::
+   :module: compute.cli.control
+   :func: get_parser
+   :prog: compute

docs/source/cli/usage.rst

@@ -0,0 +1,102 @@
+Usage
+=====
+
+Creating compute instances
+--------------------------
+
+First place your image into images pool path.
+
+Create :file:`inatance.yaml` config file with following content. Replace `debian_12.qcow2` with your actual image filename.
+
+.. code-block:: yaml
+   :caption: Using prebuilt QCOW2 disk image
+   :emphasize-lines: 4
+   :linenos:
+
+   name: myinstance
+   memory: 2048
+   vcpus: 2
+   image: debian_12.qcow2
+   volumes:
+     - type: file
+       is_system: true
+       target: vda
+       capacity:
+         value: 10
+         unit: GiB
+
+Check out what configuration will be applied when ``init``::
+
+   compute init -t
+
+Initialise instance with command::
+
+   compute init
+
+Also you can use following syntax::
+
+  compute init yourfile.yaml
+
+Start instance::
+
+   compute start myinstance
+
+Using ISO installation medium
+`````````````````````````````
+
+Download ISO image and set it as source for ``cdrom`` device.
+
+Note that the ``image`` parameter is not used here.
+
+.. code-block:: yaml
+   :caption: Using ISO image
+   :emphasize-lines: 11-13
+   :linenos:
+
+   name: myinstance
+   memory: 2048
+   vcpus: 2
+   volumes:
+     - type: file
+       is_system: true
+       target: vda
+       capacity:
+         value: 10
+         unit: GiB
+     - type: file
+       device: cdrom
+       source: /images/debian-12.2.0-amd64-netinst.iso
+
+::
+
+   compute init
+
+Now edit instance XML configuration to add VNC-server listen address::
+
+   virsh edit myinstance
+
+Add ``address`` attribute to start listen on all host network interfaces.
+
+.. code-block:: xml
+   :caption: libvirt XML config fragment
+   :emphasize-lines: 2
+   :linenos:
+
+   <graphics type='vnc' port='-1' autoport='yes' listen='0.0.0.0'>
+     <listen type='address' address='0.0.0.0'/>
+   </graphics>
+
+Also you can specify VNC server port. This is **5900** by default.
+
+Start instance and connect to VNC via any VNC client such as `Remmina <https://remmina.org/>`_ or something else.
+
+::
+
+   compute start myinstance
+
+Finish the OS installation over VNC and then do::
+
+   compute setcdrom myinstance /images/debian-12.2.0-amd64-netinst.iso --detach
+   compute powrst myinstance
+
+CDROM will be detached. ``powrst`` command will perform instance shutdown and start. Instance will booted from `vda` disk.

docs/source/conf.py

@@ -1,4 +1,3 @@
-# Add ../.. to path for autodoc Sphinx extension
 import os
 import sys
 sys.path.insert(0, os.path.abspath('../..'))
@@ -7,16 +6,18 @@ sys.path.insert(0, os.path.abspath('../..'))
 project = 'Compute'
 copyright = '2023, Compute Authors'
 author = 'Compute Authors'
-release = '0.1.0'
+release = '0.1.0-dev2'
 
 # Sphinx general settings
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx_multiversion',
+    'sphinxarg.ext',
 ]
 templates_path = ['_templates']
 exclude_patterns = []
 language = 'en'
+#pygments_style = 'monokai'
 
 # HTML output settings
 html_theme = 'alabaster'

docs/source/index.rst

@@ -3,9 +3,14 @@ Compute
 
 Compute instances management library.
 
-.. toctree::
-    :maxdepth: 1
+Contents
+--------
 
+.. toctree::
+    :maxdepth: 2
+
+    installation
+    cli/index
     pyapi/index
 
 Indices and tables

docs/source/installation.rst

@@ -0,0 +1,47 @@
+Installation
+============
+
+Install Debian 12 on your host system. If you want use virtual machine as host make sure that nested virtualization is enabled.
+
+1. Download or build ``compute`` DEB packages.
+2. Install packages::
+
+      apt-get install ./compute*
+
+3. Make sure that ``libvirtd`` and ``dnsmasq`` are enabled and running::
+
+      systemctl enable --now libvirtd.service
+      systemctl enable --now dnsmasq.service
+
+4. Prepare storage pools. You need storage pool for images and for instance volumes.
+
+   ::
+
+      for pool in images volumes; do
+          virsh pool-define-as $pool dir - - - - "/$pool"
+          virsh pool-build $pool
+          virsh pool-start $pool
+          virsh pool-autostart $pool
+      done
+
+5. Prepare env. Set environment variables in your `~/.profile`, `~/.bashrc` or global in `/etc/profile.d/compute` or `/etc/bash.bashrc`:
+
+   .. code-block:: sh
+
+      export CMP_IMAGES_POOL=images
+      export CMP_VOLUMES_POOL=volumes
+
+   Configuration file is yet not supported.
+
+   Make sure the variables are exported to the environment::
+
+      printenv | grep CMP_
+
+   If the command didn't show anything source your rc files or relogin.
+
+6. Prepare network::
+
+      virsh net-start default
+      virsh net-autostart default
+
+7. Done. Now you can follow `CLI instructions <cli/index.html>`_

docs/source/pyapi/index.rst

@@ -1,38 +1,8 @@
 Python API
 ==========
 
-The API allows you to perform actions on instances programmatically.
-
-.. code-block:: python
-
-    import compute
-
-    with compute.Session() as session:
-        instance = session.get_instance('myinstance')
-        info = instance.get_info()
-
-    print(info)
-
-
-:class:`Session` context manager provides an abstraction over :class:`libvirt.virConnect`
-and returns objects of other classes of the present library.
-
-Entity representation
----------------------
-
-Entities such as a compute-instance are represented as classes. These classes directly
-call libvirt methods to perform operations on the hypervisor. An example class is
-:class:`Volume`.
-
-The configuration files of various libvirt objects in `compute` are described by special
-dataclasses. The dataclass stores object parameters in its properties and can return an
-XML config for libvirt using the ``to_xml()`` method. For example :class:`VolumeConfig`.
-
-`Pydantic <https://docs.pydantic.dev/>`_ models are used to validate input data.
-For example :class:`VolumeSchema`.
-
-Modules documentation
----------------------
+API Reference
+-------------
 
 .. toctree::
     :maxdepth: 4

docs/source/pyapi/instance/devices.rst

@@ -0,0 +1,5 @@
+``devices``
+===========
+
+.. automodule:: compute.instance.devices
+   :members:

docs/source/pyapi/instance/index.rst

@@ -7,4 +7,5 @@
 
     instance
     guest_agent
+    devices
     schemas

docs/source/pyapi/utils.rst

@@ -12,3 +12,10 @@
 
 .. automodule:: compute.utils.ids
    :members:
+
+
+``utils.dictutil``
+------------------
+
+.. automodule:: compute.utils.dictutil
+   :members: