add docs
This commit is contained in:
parent
ffa7605201
commit
76969a37e3
5
Makefile
5
Makefile
@ -20,7 +20,10 @@ lint:
|
|||||||
docs:
|
docs:
|
||||||
poetry run sphinx-build $(DOCS_SRC) $(DOCS_BUILD)
|
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)
|
poetry run sphinx-autobuild $(DOCS_SRC) $(DOCS_BUILD)
|
||||||
|
|
||||||
clean:
|
clean:
|
||||||
|
@ -162,16 +162,16 @@ class DeviceConfig:
|
|||||||
|
|
||||||
|
|
||||||
class Instance:
|
class Instance:
|
||||||
"""Class for manipulating compute instance."""
|
"""Manage compute instances."""
|
||||||
|
|
||||||
def __init__(self, domain: libvirt.virDomain):
|
def __init__(self, domain: libvirt.virDomain):
|
||||||
"""
|
"""
|
||||||
Initialise Instance.
|
Initialise Instance.
|
||||||
|
|
||||||
:prop domain libvirt.virDomain:
|
:ivar libvirt.virDomain domain: domain object
|
||||||
:prop connection libvirt.virConnect:
|
:ivar libvirt.virConnect connection: connection object
|
||||||
:prop name str:
|
:ivar str name: domain name
|
||||||
:prop guest_agent GuestAgent:
|
:ivar GuestAgent guest_agent: :class:`GuestAgent` object
|
||||||
|
|
||||||
:param domain: libvirt domain object
|
:param domain: libvirt domain object
|
||||||
"""
|
"""
|
||||||
|
@ -44,27 +44,27 @@ class CPUSchema(BaseModel):
|
|||||||
features: CPUFeaturesSchema
|
features: CPUFeaturesSchema
|
||||||
|
|
||||||
|
|
||||||
class StorageVolumeType(StrEnum):
|
class VolumeType(StrEnum):
|
||||||
"""Storage volume types enumeration."""
|
"""Storage volume types enumeration."""
|
||||||
|
|
||||||
FILE = 'file'
|
FILE = 'file'
|
||||||
NETWORK = 'network'
|
NETWORK = 'network'
|
||||||
|
|
||||||
|
|
||||||
class StorageVolumeCapacitySchema(BaseModel):
|
class VolumeCapacitySchema(BaseModel):
|
||||||
"""Storage volume capacity field model."""
|
"""Storage volume capacity field model."""
|
||||||
|
|
||||||
value: int
|
value: int
|
||||||
unit: DataUnit
|
unit: DataUnit
|
||||||
|
|
||||||
|
|
||||||
class StorageVolumeSchema(BaseModel):
|
class VolumeSchema(BaseModel):
|
||||||
"""Storage volume model."""
|
"""Storage volume model."""
|
||||||
|
|
||||||
type: StorageVolumeType # noqa: A003
|
type: VolumeType # noqa: A003
|
||||||
source: Path
|
source: Path
|
||||||
target: str
|
target: str
|
||||||
capacity: StorageVolumeCapacitySchema
|
capacity: VolumeCapacitySchema
|
||||||
readonly: bool = False
|
readonly: bool = False
|
||||||
is_system: bool = False
|
is_system: bool = False
|
||||||
|
|
||||||
@ -98,7 +98,7 @@ class InstanceSchema(BaseModel):
|
|||||||
arch: str
|
arch: str
|
||||||
image: str
|
image: str
|
||||||
boot: BootOptionsSchema
|
boot: BootOptionsSchema
|
||||||
volumes: list[StorageVolumeSchema]
|
volumes: list[VolumeSchema]
|
||||||
network_interfaces: list[NetworkInterfaceSchema]
|
network_interfaces: list[NetworkInterfaceSchema]
|
||||||
|
|
||||||
@validator('name')
|
@validator('name')
|
||||||
|
@ -29,16 +29,25 @@ class Capabilities(NamedTuple):
|
|||||||
|
|
||||||
|
|
||||||
class Session(AbstractContextManager):
|
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):
|
def __init__(self, uri: str | None = None):
|
||||||
"""
|
"""
|
||||||
Initialise session with hypervisor.
|
Initialise session with hypervisor.
|
||||||
|
|
||||||
|
:ivar str uri: libvirt connection URI.
|
||||||
|
:ivar libvirt.virConnect connection: libvirt connection object.
|
||||||
|
|
||||||
:param uri: libvirt connection URI.
|
: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.uri = uri or 'qemu:///system'
|
||||||
self.connection = libvirt.open(self.uri)
|
self.connection = libvirt.open(self.uri)
|
||||||
|
|
||||||
@ -74,11 +83,16 @@ class Session(AbstractContextManager):
|
|||||||
"""
|
"""
|
||||||
Create and return new compute instance.
|
Create and return new compute instance.
|
||||||
|
|
||||||
:param name str: Instance name.
|
:param name: Instance name.
|
||||||
:param title str: Instance title for humans.
|
:type name: str
|
||||||
:param description str: Some information about instance
|
:param title: Instance title for humans.
|
||||||
:param memory int: Memory in MiB.
|
:type title: str
|
||||||
:param max_memory int: Maximum memory in MiB.
|
: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
|
# TODO @ge: create instances in transaction
|
||||||
data = InstanceSchema(**kwargs)
|
data = InstanceSchema(**kwargs)
|
||||||
|
@ -24,7 +24,7 @@ class InvalidDataUnitError(ValueError):
|
|||||||
|
|
||||||
|
|
||||||
def to_bytes(value: int, unit: DataUnit = DataUnit.BYTES) -> int:
|
def to_bytes(value: int, unit: DataUnit = DataUnit.BYTES) -> int:
|
||||||
"""Convert value to bytes. See `DataUnit`."""
|
"""Convert value to bytes. See :class:`DataUnit`."""
|
||||||
try:
|
try:
|
||||||
_ = DataUnit(unit)
|
_ = DataUnit(unit)
|
||||||
except ValueError as e:
|
except ValueError as e:
|
||||||
|
@ -1,5 +1,5 @@
|
|||||||
{% if versions %}
|
{% if versions %}
|
||||||
<h3>{{ _('Versions') }}</h3>
|
<h3>{{ _('Версии') }}</h3>
|
||||||
<ul>
|
<ul>
|
||||||
{%- for item in versions %}
|
{%- for item in versions %}
|
||||||
<li><a href="{{ item.url }}">{{ item.name }}</a></li>
|
<li><a href="{{ item.url }}">{{ item.name }}</a></li>
|
||||||
|
@ -1,35 +1,32 @@
|
|||||||
# Configuration file for the Sphinx documentation builder.
|
import os
|
||||||
#
|
import sys
|
||||||
# For the full list of built-in configuration values, see the documentation:
|
sys.path.insert(0, os.path.abspath('../../compute'))
|
||||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
|
||||||
|
|
||||||
# -- Project information -----------------------------------------------------
|
|
||||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
|
||||||
|
|
||||||
|
# Project information
|
||||||
project = 'Compute'
|
project = 'Compute'
|
||||||
copyright = '2023, Compute Authors'
|
copyright = '2023, Compute Authors'
|
||||||
author = 'Compute Authors'
|
author = 'Compute Authors'
|
||||||
release = '0.1.0'
|
release = '0.1.0'
|
||||||
|
|
||||||
# -- General configuration ---------------------------------------------------
|
# Sphinx general settings
|
||||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
extensions = [
|
||||||
|
'sphinx.ext.autodoc',
|
||||||
extensions = []
|
'sphinx_multiversion',
|
||||||
|
]
|
||||||
templates_path = ['_templates']
|
templates_path = ['_templates']
|
||||||
exclude_patterns = []
|
exclude_patterns = []
|
||||||
|
|
||||||
language = 'ru'
|
language = 'ru'
|
||||||
|
|
||||||
extensions = [
|
# HTML output settings
|
||||||
"sphinx_multiversion",
|
|
||||||
]
|
|
||||||
|
|
||||||
# -- Options for HTML output -------------------------------------------------
|
|
||||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
|
||||||
|
|
||||||
html_theme = 'alabaster'
|
html_theme = 'alabaster'
|
||||||
html_static_path = ['_static']
|
html_static_path = ['_static']
|
||||||
html_sidebars = [
|
html_sidebars = {
|
||||||
"versioning.html",
|
'**': [
|
||||||
]
|
'about.html',
|
||||||
|
'navigation.html',
|
||||||
|
'relations.html',
|
||||||
|
'searchbox.html',
|
||||||
|
'donate.html',
|
||||||
|
'versioning.html',
|
||||||
|
]
|
||||||
|
}
|
||||||
|
@ -4,8 +4,9 @@ Compute Service
|
|||||||
Документация библиотеки для управления Compute-инстансами.
|
Документация библиотеки для управления Compute-инстансами.
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 1
|
||||||
:caption: Contents:
|
|
||||||
|
python-api/index
|
||||||
|
|
||||||
Индексы и таблицы
|
Индексы и таблицы
|
||||||
-----------------
|
-----------------
|
||||||
|
47
docs/source/python-api/index.rst
Normal file
47
docs/source/python-api/index.rst
Normal file
@ -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
|
5
docs/source/python-api/instance/guest_agent.rst
Normal file
5
docs/source/python-api/instance/guest_agent.rst
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
``guest_agent``
|
||||||
|
===============
|
||||||
|
|
||||||
|
.. automodule:: compute.instance.guest_agent
|
||||||
|
:members:
|
10
docs/source/python-api/instance/index.rst
Normal file
10
docs/source/python-api/instance/index.rst
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
``instance``
|
||||||
|
============
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
:caption: Содержание:
|
||||||
|
|
||||||
|
instance
|
||||||
|
guest_agent
|
||||||
|
schemas
|
6
docs/source/python-api/instance/instance.rst
Normal file
6
docs/source/python-api/instance/instance.rst
Normal file
@ -0,0 +1,6 @@
|
|||||||
|
``instance``
|
||||||
|
============
|
||||||
|
|
||||||
|
.. automodule:: compute.instance.instance
|
||||||
|
:members:
|
||||||
|
:special-members:
|
5
docs/source/python-api/instance/schemas.rst
Normal file
5
docs/source/python-api/instance/schemas.rst
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
``schemas``
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. automodule:: compute.instance.schemas
|
||||||
|
:members:
|
9
docs/source/python-api/session.rst
Normal file
9
docs/source/python-api/session.rst
Normal file
@ -0,0 +1,9 @@
|
|||||||
|
``session``
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. autoclass:: compute.Session
|
||||||
|
:members:
|
||||||
|
:special-members:
|
||||||
|
|
||||||
|
.. autoclass:: compute.session.Capabilities
|
||||||
|
:members:
|
14
docs/source/python-api/storage.rst
Normal file
14
docs/source/python-api/storage.rst
Normal file
@ -0,0 +1,14 @@
|
|||||||
|
``storage``
|
||||||
|
===========
|
||||||
|
|
||||||
|
``compute.storage.pool``
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
.. automodule:: compute.storage.pool
|
||||||
|
:members:
|
||||||
|
|
||||||
|
``compute.storage.volume``
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
.. automodule:: compute.storage.volume
|
||||||
|
:members:
|
@ -18,7 +18,6 @@ compute = "compute.cli.control:cli"
|
|||||||
ruff = "^0.1.3"
|
ruff = "^0.1.3"
|
||||||
isort = "^5.12.0"
|
isort = "^5.12.0"
|
||||||
|
|
||||||
|
|
||||||
[tool.poetry.group.docs.dependencies]
|
[tool.poetry.group.docs.dependencies]
|
||||||
sphinx = "^7.2.6"
|
sphinx = "^7.2.6"
|
||||||
sphinx-autobuild = "^2021.3.14"
|
sphinx-autobuild = "^2021.3.14"
|
||||||
|
Loading…
Reference in New Issue
Block a user