Add SDK docs (#4928)

- Added auth docs in API schema and SDK ApiClient/Config (fixes #1517) - Added SDK docs with API, SDK and CLI docs - Added `develop` branch in the docs - Allowed unauthorized access to `api/docs`, `api/swagger`, `api/schema` endpoints - Added `--insecure` env var to control host checks in CLI - Refactored `build_docs.py` (backported openvinotoolkit/datumaro#589) - Extracted requirements file for site
cvat-ai · Sep 15, 2022 · 68375ec · 68375ec
1 parent cf4e071
commit 68375ec
Show file tree

Hide file tree

Showing 30 changed files with 1,561 additions and 291 deletions.
diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml
@@ -32,7 +32,7 @@ jobs:
 
       - name: Build docs
         run: |
-          pip install gitpython packaging toml
+          pip install -r site/requirements.txt
           python site/build_docs.py
 
       - name: Deploy

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,10 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## \[2.3.0] - Unreleased
 ### Added
-- TDB
+- SDK section in docs (<https://github.com/opencv/cvat/pull/4928>)
+- An env variable to enable or disable host certificate checking in CLI (<https://github.com/opencv/cvat/pull/4928>)
 
 ### Changed
-- TDB
+- `api/docs`, `api/swagger`, `api/schema` endpoints now allow unauthorized access (<https://github.com/opencv/cvat/pull/4928>)
 
 ### Deprecated
 - TDB

diff --git a/README.md b/README.md
@@ -30,9 +30,10 @@ Start using CVAT online for free: [cvat.ai](https://cvat.ai). Or set it up as a
 - [Installation guide](https://opencv.github.io/cvat/docs/administration/basics/installation/)
 - [Manual](https://opencv.github.io/cvat/docs/manual/)
 - [Contributing](https://opencv.github.io/cvat/docs/contributing/)
-- [Django REST API documentation](https://opencv.github.io/cvat/docs/administration/basics/rest_api_guide/)
 - [Datumaro dataset framework](https://github.com/cvat-ai/datumaro/blob/develop/README.md)
-- [Command line interface](https://opencv.github.io/cvat/docs/manual/advanced/cli/)
+- [Server API](#api)
+- [Python SDK](#sdk)
+- [Command line tool](#cli)
 - [XML annotation format](https://opencv.github.io/cvat/docs/manual/advanced/xml_format/)
 - [AWS Deployment Guide](https://opencv.github.io/cvat/docs/administration/basics/aws-deployment-guide/)
 - [Frequently asked questions](https://opencv.github.io/cvat/docs/faq/)
@@ -85,11 +86,6 @@ Prebuilt docker images are the easiest way to start using CVAT locally. They are
 
 The images have been downloaded more than 1M times so far.
 
-## REST API
-
-CVAT has a REST API: [documentation](https://opencv.github.io/cvat/docs/administration/basics/rest_api_guide/).
-Its current version is `2.0-alpha`. We focus on its improvement, and the API may be changed in the next releases.
-
 ## Screencasts 🎦
 
 Here are some screencasts showing how to use CVAT.
@@ -104,6 +100,22 @@ Here are some screencasts showing how to use CVAT.
 - [Tutorial for polygons](https://youtu.be/C7-r9lZbjBw)
 - [Semi-automatic segmentation](https://youtu.be/9HszWP_qsRQ)
 
+## API
+
+- [Documentation](https://opencv.github.io/cvat/docs/api_sdk/api/)
+
+## SDK
+
+- Install with `pip install cvat-sdk`
+- [PyPI package homepage](https://pypi.org/project/cvat-sdk/)
+- [Documentation](https://opencv.github.io/cvat/docs/api_sdk/sdk/)
+
+## CLI
+
+- Install with `pip install cvat-cli`
+- [PyPI package homepage](https://pypi.org/project/cvat-cli/)
+- [Documentation](https://opencv.github.io/cvat/docs/api_sdk/cli/)
+
 ## Supported annotation formats
 
 CVAT supports multiple annotation formats. You can select the format after clicking the "Upload annotation" and "Dump

diff --git a/cvat-cli/src/cvat_cli/__main__.py b/cvat-cli/src/cvat_cli/__main__.py
@@ -6,9 +6,11 @@
 import logging
 import sys
 from http.client import HTTPConnection
+from types import SimpleNamespace
 from typing import List
 
-from cvat_sdk import exceptions, make_client
+from cvat_sdk import exceptions
+from cvat_sdk.core.client import Client, Config
 
 from cvat_cli.cli import CLI
 from cvat_cli.parser import get_action_args, make_cmdline_parser
@@ -28,6 +30,16 @@ def configure_logger(level):
         HTTPConnection.debuglevel = 1
 
 
+def build_client(parsed_args: SimpleNamespace, logger: logging.Logger) -> Client:
+    config = Config(verify_ssl=not parsed_args.insecure)
+
+    return Client(
+        url="{host}:{port}".format(host=parsed_args.server_host, port=parsed_args.server_port),
+        logger=logger,
+        config=config,
+    )
+
+
 def main(args: List[str] = None):
     actions = {
         "create": CLI.tasks_create,
@@ -43,9 +55,7 @@ def main(args: List[str] = None):
     parsed_args = parser.parse_args(args)
     configure_logger(parsed_args.loglevel)
 
-    with make_client(parsed_args.server_host, port=parsed_args.server_port) as client:
-        client.logger = logger
-
+    with build_client(parsed_args, logger=logger) as client:
         action_args = get_action_args(parser, parsed_args)
         try:
             cli = CLI(client=client, credentials=parsed_args.auth)

diff --git a/cvat-cli/src/cvat_cli/parser.py b/cvat-cli/src/cvat_cli/parser.py
@@ -47,6 +47,11 @@ def make_cmdline_parser() -> argparse.ArgumentParser:
         description="Perform common operations related to CVAT tasks.\n\n"
     )
     parser.add_argument("--version", action="version", version=VERSION)
+    parser.add_argument(
+        "--insecure",
+        action="store_true",
+        help="Allows to disable SSL certificate check",
+    )
 
     task_subparser = parser.add_subparsers(dest="action")
 

diff --git a/cvat-sdk/cvat_sdk/core/client.py b/cvat-sdk/cvat_sdk/core/client.py
@@ -31,6 +31,11 @@ class Config:
     status_check_period: float = 5
     """In seconds"""
 
+    verify_ssl: Optional[bool] = None
+    """
+    Whether to verify host SSL certificate or not.
+    """
+
 
 class Client:
     """
@@ -41,10 +46,12 @@ def __init__(
         self, url: str, *, logger: Optional[logging.Logger] = None, config: Optional[Config] = None
     ):
         url = self._validate_and_prepare_url(url)
-        self.api_map = CVAT_API_V2(url)
-        self.api_client = ApiClient(Configuration(host=self.api_map.host))
         self.logger = logger or logging.getLogger(__name__)
         self.config = config or Config()
+        self.api_map = CVAT_API_V2(url)
+        self.api_client = ApiClient(
+            Configuration(host=self.api_map.host, verify_ssl=self.config.verify_ssl)
+        )
 
         self._repos: Dict[str, Repo] = {}
 
@@ -76,7 +83,7 @@ def _detect_schema(cls, base_url: str) -> str:
         for schema in cls.ALLOWED_SCHEMAS:
             with ApiClient(Configuration(host=f"{schema}://{base_url}")) as api_client:
                 with suppress(urllib3.exceptions.RequestError):
-                    (_, response) = api_client.schema_api.retrieve(
+                    (_, response) = api_client.server_api.retrieve_about(
                         _request_timeout=5, _parse_response=False, _check_status=False
                     )
 

diff --git a/cvat-sdk/developer_guide.md b/cvat-sdk/developer_guide.md
diff --git a/cvat-sdk/gen/templates/openapi-generator/README.mustache b/cvat-sdk/gen/templates/openapi-generator/README.mustache
@@ -16,36 +16,21 @@ For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
 {{/infoUrl}}
 
 ## Installation & Usage
-### pip install
 
-If the python package is hosted on a repository, you can install directly using:
+To install a prebuilt package, run the following command in the terminal:
 
 ```sh
-pip install git+https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}.git
+pip install cvat-sdk
 ```
-(you may need to run `pip` with root permission: `sudo pip install git+https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}.git`)
 
-Then import the package:
-```python
-import {{{packageName}}}
-```
+To install from the local directory, follow [the developer guide](https://opencv.github.io/cvat/docs/integration/sdk/developer_guide).
 
-### Setuptools
+After installation you can import the package:
 
-Install via [Setuptools](http://pypi.python.org/pypi/setuptools).
-
-```sh
-python setup.py install --user
-```
-(or `sudo python setup.py install` to install the package for all users)
-
-Then import the package:
 ```python
-import {{{packageName}}}
+import cvat_sdk
 ```
 
 ## Getting Started
 
-Please follow the [installation procedure](#installation--usage) and then run the following:
-
 {{> README_common }}