add docs

Makefile

@@ -20,7 +20,10 @@ lint:
 docs:
 	poetry run sphinx-build $(DOCS_SRC) $(DOCS_BUILD)
 
-serve-docs:
+docs-versions:
+	poetry run sphinx-multiversion $(DOCS_SRC) $(DOCS_BUILD)
+
+serve-docs: docs-versions
 	poetry run sphinx-autobuild $(DOCS_SRC) $(DOCS_BUILD)
 
 clean:

compute/instance/instance.py

@@ -162,16 +162,16 @@ class DeviceConfig:
 
 
 class Instance:
-    """Class for manipulating compute instance."""
+    """Manage compute instances."""
 
     def __init__(self, domain: libvirt.virDomain):
         """
         Initialise Instance.
 
-        :prop domain libvirt.virDomain:
-        :prop connection libvirt.virConnect:
-        :prop name str:
-        :prop guest_agent GuestAgent:
+        :ivar libvirt.virDomain domain: domain object
+        :ivar libvirt.virConnect connection: connection object
+        :ivar str name: domain name
+        :ivar GuestAgent guest_agent: :class:`GuestAgent` object
 
         :param domain: libvirt domain object
         """

compute/instance/schemas.py

@@ -44,27 +44,27 @@ class CPUSchema(BaseModel):
     features: CPUFeaturesSchema
 
 
-class StorageVolumeType(StrEnum):
+class VolumeType(StrEnum):
     """Storage volume types enumeration."""
 
     FILE = 'file'
     NETWORK = 'network'
 
 
-class StorageVolumeCapacitySchema(BaseModel):
+class VolumeCapacitySchema(BaseModel):
     """Storage volume capacity field model."""
 
     value: int
     unit: DataUnit
 
 
-class StorageVolumeSchema(BaseModel):
+class VolumeSchema(BaseModel):
     """Storage volume model."""
 
-    type: StorageVolumeType  # noqa: A003
+    type: VolumeType  # noqa: A003
     source: Path
     target: str
-    capacity: StorageVolumeCapacitySchema
+    capacity: VolumeCapacitySchema
     readonly: bool = False
     is_system: bool = False
 
@@ -98,7 +98,7 @@ class InstanceSchema(BaseModel):
     arch: str
     image: str
     boot: BootOptionsSchema
-    volumes: list[StorageVolumeSchema]
+    volumes: list[VolumeSchema]
     network_interfaces: list[NetworkInterfaceSchema]
 
     @validator('name')

compute/session.py

@@ -29,16 +29,25 @@ class Capabilities(NamedTuple):
 
 
 class Session(AbstractContextManager):
-    """Hypervisor session manager."""
+    """
+    Hypervisor session context manager.
+
+    :cvar IMAGES_POOL: images storage pool name taken from env
+    :cvar VOLUMES_POOL: volumes storage pool name taken from env
+    """
+
+    IMAGES_POOL = os.getenv('CMP_IMAGES_POOL')
+    VOLUMES_POOL = os.getenv('CMP_VOLUMES_POOL')
 
     def __init__(self, uri: str | None = None):
         """
         Initialise session with hypervisor.
 
+        :ivar str uri: libvirt connection URI.
+        :ivar libvirt.virConnect connection: libvirt connection object.
+
         :param uri: libvirt connection URI.
         """
-        self.IMAGES_POOL = os.getenv('CMP_IMAGES_POOL')
-        self.VOLUMES_POOL = os.getenv('CMP_VOLUMES_POOL')
         self.uri = uri or 'qemu:///system'
         self.connection = libvirt.open(self.uri)
 
@@ -74,11 +83,16 @@ class Session(AbstractContextManager):
         """
         Create and return new compute instance.
 
-        :param name str: Instance name.
-        :param title str: Instance title for humans.
-        :param description str: Some information about instance
-        :param memory int: Memory in MiB.
-        :param max_memory int: Maximum memory in MiB.
+        :param name: Instance name.
+        :type name: str
+        :param title: Instance title for humans.
+        :type title: str
+        :param description: Some information about instance
+        :type description: str
+        :param memory: Memory in MiB.
+        :type memory: int
+        :param max_memory: Maximum memory in MiB.
+        :type max_memory: int
         """
         # TODO @ge: create instances in transaction
         data = InstanceSchema(**kwargs)

compute/utils/units.py

@@ -24,7 +24,7 @@ class InvalidDataUnitError(ValueError):
 
 
 def to_bytes(value: int, unit: DataUnit = DataUnit.BYTES) -> int:
-    """Convert value to bytes. See `DataUnit`."""
+    """Convert value to bytes. See :class:`DataUnit`."""
     try:
         _ = DataUnit(unit)
     except ValueError as e:

docs/source/_templates/versioning.html

@@ -1,5 +1,5 @@
 {% if versions %}
-<h3>{{ _('Versions') }}</h3>
+<h3>{{ _('Версии') }}</h3>
 <ul>
   {%- for item in versions %}
   <li><a href="{{ item.url }}">{{ item.name }}</a></li>

docs/source/conf.py

@@ -1,35 +1,32 @@
-# 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('../../compute'))
 
+# Project information
 project = 'Compute'
 copyright = '2023, Compute Authors'
 author = 'Compute Authors'
 release = '0.1.0'
 
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-extensions = []
-
+# Sphinx general settings
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx_multiversion',
+]
 templates_path = ['_templates']
 exclude_patterns = []
-
 language = 'ru'
 
-extensions = [
-    "sphinx_multiversion",
-]
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
+# HTML output settings
 html_theme = 'alabaster'
 html_static_path = ['_static']
-html_sidebars = [
-    "versioning.html",
-]
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'relations.html',
+        'searchbox.html',
+        'donate.html',
+        'versioning.html',
+    ]
+}

docs/source/index.rst

@@ -4,8 +4,9 @@ Compute Service
 Документация библиотеки для управления Compute-инстансами.
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+    :maxdepth: 1
+
+    python-api/index
 
 Индексы и таблицы
 -----------------

docs/source/python-api/index.rst

@@ -0,0 +1,47 @@
+Python API
+==========
+
+API позволяет выполнять действия над инстансами программно. Ниже описано пример
+изменения параметров и запуска инстанса `myinstance`.
+
+.. code-block:: python
+
+    import logging
+
+    from compute import Session
+
+
+    logging.basicConfig(level=logging.DEBUG)
+
+    with Session() as session:
+        instance = session.get_instance('myinstance')
+        instance.set_vcpus(4)
+        instance.start()
+        instance.set_autostart(enabled=True)
+
+
+Контекстный менеджер :class:`Session` предоставляет абстракцию над :class:`libvirt.virConnect`
+и возвращает объекты других классов настоящей билиотеки.
+
+Представление сущностей
+-----------------------
+
+Такие сущности как Сompute-инстанс представлены в виде классов. Эти классы напрямую
+вызывают методы libvirt для выполнения операций на гипервизоре. Пример класса — :data:`Volume`.
+
+Конфигурационные файлы различных объектов libvirt в compute описаны специальными
+датаклассами. Датакласс хранит в своих свойствах параметры объекта и может вернуть XML
+конфиг для libvirt с помощью метода ``to_xml()``. Пример — :py:class:`VolumeConfig`.
+
+Для валидации входных данных используются модели `Pydantic <https://docs.pydantic.dev/>`_.
+Пример — :py:class:`VolumeSchema`.
+
+Документация модулей
+--------------------
+
+.. toctree::
+    :maxdepth: 4
+
+    session
+    instance/index
+    storage

docs/source/python-api/instance/guest_agent.rst

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

docs/source/python-api/instance/index.rst

@@ -0,0 +1,10 @@
+``instance``
+============
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Содержание:
+    
+    instance
+    guest_agent
+    schemas

docs/source/python-api/instance/instance.rst

@@ -0,0 +1,6 @@
+``instance``
+============
+
+.. automodule:: compute.instance.instance
+   :members:
+   :special-members:

docs/source/python-api/instance/schemas.rst

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

docs/source/python-api/session.rst

@@ -0,0 +1,9 @@
+``session``
+===========
+
+.. autoclass:: compute.Session
+   :members:
+   :special-members:
+
+.. autoclass:: compute.session.Capabilities
+   :members:

docs/source/python-api/storage.rst

@@ -0,0 +1,14 @@
+``storage``
+===========
+
+``compute.storage.pool``
+------------------------
+
+.. automodule:: compute.storage.pool
+   :members:
+
+``compute.storage.volume``
+--------------------------
+
+.. automodule:: compute.storage.volume
+   :members:

pyproject.toml

@@ -18,7 +18,6 @@ compute = "compute.cli.control:cli"
 ruff = "^0.1.3"
 isort = "^5.12.0"
 
-
 [tool.poetry.group.docs.dependencies]
 sphinx = "^7.2.6"
 sphinx-autobuild = "^2021.3.14"