diff --git a/Makefile b/Makefile
index 2444722..2e55cae 100644
--- a/Makefile
+++ b/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:
diff --git a/compute/instance/instance.py b/compute/instance/instance.py
index f5bfe75..21e8d22 100644
--- a/compute/instance/instance.py
+++ b/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
"""
diff --git a/compute/instance/schemas.py b/compute/instance/schemas.py
index f19853f..5fa9aad 100644
--- a/compute/instance/schemas.py
+++ b/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')
diff --git a/compute/session.py b/compute/session.py
index 7e2945a..0de990e 100644
--- a/compute/session.py
+++ b/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)
diff --git a/compute/utils/units.py b/compute/utils/units.py
index 6146a59..7e4b632 100644
--- a/compute/utils/units.py
+++ b/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:
diff --git a/docs/source/_templates/versioning.html b/docs/source/_templates/versioning.html
index 7c5ab14..318bd87 100644
--- a/docs/source/_templates/versioning.html
+++ b/docs/source/_templates/versioning.html
@@ -1,5 +1,5 @@
{% if versions %}
-
{{ _('Versions') }}
+{{ _('Версии') }}
{%- for item in versions %}
- {{ item.name }}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index cbd5572..7e83ba6 100644
--- a/docs/source/conf.py
+++ b/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',
+ ]
+}
diff --git a/docs/source/index.rst b/docs/source/index.rst
index a2a34dc..634116c 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -4,8 +4,9 @@ Compute Service
Документация библиотеки для управления Compute-инстансами.
.. toctree::
- :maxdepth: 2
- :caption: Contents:
+ :maxdepth: 1
+
+ python-api/index
Индексы и таблицы
-----------------
diff --git a/docs/source/python-api/index.rst b/docs/source/python-api/index.rst
new file mode 100644
index 0000000..be20c7f
--- /dev/null
+++ b/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 `_.
+Пример — :py:class:`VolumeSchema`.
+
+Документация модулей
+--------------------
+
+.. toctree::
+ :maxdepth: 4
+
+ session
+ instance/index
+ storage
diff --git a/docs/source/python-api/instance/guest_agent.rst b/docs/source/python-api/instance/guest_agent.rst
new file mode 100644
index 0000000..82d6b7d
--- /dev/null
+++ b/docs/source/python-api/instance/guest_agent.rst
@@ -0,0 +1,5 @@
+``guest_agent``
+===============
+
+.. automodule:: compute.instance.guest_agent
+ :members:
diff --git a/docs/source/python-api/instance/index.rst b/docs/source/python-api/instance/index.rst
new file mode 100644
index 0000000..d0ee0ba
--- /dev/null
+++ b/docs/source/python-api/instance/index.rst
@@ -0,0 +1,10 @@
+``instance``
+============
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Содержание:
+
+ instance
+ guest_agent
+ schemas
diff --git a/docs/source/python-api/instance/instance.rst b/docs/source/python-api/instance/instance.rst
new file mode 100644
index 0000000..bf3d255
--- /dev/null
+++ b/docs/source/python-api/instance/instance.rst
@@ -0,0 +1,6 @@
+``instance``
+============
+
+.. automodule:: compute.instance.instance
+ :members:
+ :special-members:
diff --git a/docs/source/python-api/instance/schemas.rst b/docs/source/python-api/instance/schemas.rst
new file mode 100644
index 0000000..7dacabf
--- /dev/null
+++ b/docs/source/python-api/instance/schemas.rst
@@ -0,0 +1,5 @@
+``schemas``
+===========
+
+.. automodule:: compute.instance.schemas
+ :members:
diff --git a/docs/source/python-api/session.rst b/docs/source/python-api/session.rst
new file mode 100644
index 0000000..6414a7b
--- /dev/null
+++ b/docs/source/python-api/session.rst
@@ -0,0 +1,9 @@
+``session``
+===========
+
+.. autoclass:: compute.Session
+ :members:
+ :special-members:
+
+.. autoclass:: compute.session.Capabilities
+ :members:
diff --git a/docs/source/python-api/storage.rst b/docs/source/python-api/storage.rst
new file mode 100644
index 0000000..5b24aeb
--- /dev/null
+++ b/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:
diff --git a/pyproject.toml b/pyproject.toml
index a4dd55d..919fef1 100644
--- a/pyproject.toml
+++ b/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"