Basic documentation (#47)

Co-authored-by: Roman Solomatin <[email protected]>

Author: voorhs

.github/workflows/ruff.yml

@@ -5,4 +5,4 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: chartboost/ruff-action@v1
+      - uses: astral-sh/ruff-action@v1

.gitignore

@@ -69,7 +69,9 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
+docs/source/apiref
+docs/source/tutorials
 
 # PyBuilder
 .pybuilder/

.vscode/settings.json

@@ -1,3 +1,6 @@
 {
-    "ruff.configuration": "pyproject.toml"
+    "ruff.configuration": "pyproject.toml",
+    "python.analysis.extraPaths": [
+        "./docs/source"
+    ]
 }

CONTRIBUTING.md

@@ -83,4 +83,16 @@ embedder_batch_size: 32
 4. Запускаем с конфиг файлом config.yaml:
 ```bash
 autointent --config-path FULL_PATH/test_config --config-name config
-```
+```
+
+## Построение документации
+
+Построить html версию в папке `docs/build`:
+```bash
+make docs
+```
+
+Построить html версию и захостить локально:
+```bash
+make serve-docs
+```

Makefile

@@ -3,7 +3,7 @@ poetry = poetry run
 
 .PHONY: install
 install:
-	poetry install --with dev,test,lint,typing
+	poetry install --with dev,test,lint,typing,docs
 
 .PHONY: test
 test:
@@ -22,5 +22,18 @@ lint:
 	$(poetry) ruff format
 	$(poetry) ruff check --fix
 
+.PHONY: sync
+sync:
+	poetry install --sync --with dev,test,lint,typing,docs
+
+.PHONY: docs
+docs:
+	$(poetry) sphinx-apidoc -e -E -f --remove-old -o docs/source/apiref autointent
+	$(poetry) python -m sphinx build docs/source docs/build/html
+
+.PHONY: serve-docs
+serve-docs: docs
+	$(poetry) python -m http.server -d docs/build/html 8333
+
 .PHONY: all
 all: lint

README.md

@@ -377,10 +377,3 @@ Prediction:
     - `prediction_recall`
     - `prediction_roc_auc`
 
-## Roadmap
-
-| Version | Description                                               |
-| ------- | --------------------------------------------------------- |
-| v0.0.x  | Python API, CLI API, Greedy optimization                  |
-| v0.1.x  | Web UI for logging, Bayes optimization, data augmentation |
-| v0.2.x  | Optimization presets, improved efficiency                 |

autointent/configs/__init__.py

@@ -0,0 +1,28 @@
+from .inference_cli import InferenceConfig
+from .inference_pipeline import InferencePipelineConfig
+from .node import InferenceNodeConfig, NodeOptimizerConfig
+from .optimization_cli import (
+    AugmentationConfig,
+    DataConfig,
+    EmbedderConfig,
+    LoggingConfig,
+    OptimizationConfig,
+    TaskConfig,
+    VectorIndexConfig,
+)
+from .pipeline_optimizer import PipelineOptimizerConfig
+
+__all__ = [
+    "AugmentationConfig",
+    "DataConfig",
+    "EmbedderConfig",
+    "InferenceConfig",
+    "InferenceNodeConfig",
+    "InferencePipelineConfig",
+    "LoggingConfig",
+    "NodeOptimizerConfig",
+    "OptimizationConfig",
+    "PipelineOptimizerConfig",
+    "TaskConfig",
+    "VectorIndexConfig",
+]

autointent/configs/inference_cli.py

@@ -1,3 +1,5 @@
+"""Inference CLI configuration module."""
+
 from dataclasses import dataclass
 
 from hydra.core.config_store import ConfigStore
@@ -7,11 +9,18 @@
 
 @dataclass
 class InferenceConfig:
+    """Configuration for the inference process."""
+
     data_path: str
+    """Path to the file containing the data for prediction"""
     source_dir: str
+    """Path to the directory containing the inference config"""
     output_path: str
+    """Path to the file where the predictions will be saved"""
     log_level: LogLevel = LogLevel.ERROR
+    """Logging level"""
     with_metadata: bool = False
+    """Whether to save metadata along with the predictions"""
 
 
 cs = ConfigStore.instance()

autointent/configs/inference_pipeline.py

@@ -1,3 +1,5 @@
+"""Configuration for the inference pipeline."""
+
 from dataclasses import dataclass
 
 from omegaconf import MISSING
@@ -7,5 +9,8 @@
 
 @dataclass
 class InferencePipelineConfig:
+    """Configuration for the inference pipeline."""
+
     nodes: list[InferenceNodeConfig] = MISSING
+    """List of nodes in the inference pipeline"""
     _target_: str = "autointent.pipeline.InferencePipeline"

autointent/configs/name.py

@@ -1,3 +1,5 @@
+"""Random name generator."""
+
 import random
 from datetime import datetime
 
@@ -340,12 +342,23 @@
 
 
 def generate_name() -> str:
+    """
+    Generate a random name for a run.
+
+    :return: Random name
+    """
     adjective = random.choice(adjectives)
     noun = random.choice(nouns)
     return f"{adjective}_{noun}"
 
 
 def get_run_name(run_name: str | None = None) -> str:
+    """
+    Get a run name.
+
+    :param run_name: Run name. If None, generate a random name
+    :return: Run name with a timestamp
+    """
     if run_name is None:
         run_name = generate_name()
     return f"{run_name}_{datetime.now().strftime('%m-%d-%Y_%H-%M-%S')}"  # noqa: DTZ005