Add SDK docs

.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

CHANGELOG.md

@@ -37,6 +37,7 @@ Skeleton (<https://github.com/cvat-ai/cvat/pull/1>), (<https://github.com/opencv
 - cvat-ui: Improve UI/UX on label, create task and create project forms (<https://github.com/cvat-ai/cvat/pull/7>)
 - Removed link to OpenVINO documentation (<https://github.com/cvat-ai/cvat/pull/35>)
 - Clarified meaning of chunking for videos
+- Added `integration` section in docs, added `develop` version docs
 
 ### Deprecated
 - TDB

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](https://opencv.github.io/cvat/docs/integration/api/)
+- [Python SDK](https://opencv.github.io/cvat/docs/integration/sdk/)
+- [Command line tool](https://opencv.github.io/cvat/docs/integration/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,10 +86,23 @@ 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
+## Integration
 
-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.
+### Server API
+
+- [Documentation](https://opencv.github.io/cvat/docs/integration/api/)
+
+### Python SDK
+
+- Install with `pip install cvat-sdk`
+- [PyPI package homepage](https://pypi.org/project/cvat-sdk/)
+- [Documentation](https://opencv.github.io/cvat/docs/integration/sdk/)
+
+### CLI
+
+- Install with `pip install cvat-cli`
+- [PyPI package homepage](https://pypi.org/project/cvat-cli/)
+- [Documentation](https://opencv.github.io/cvat/docs/integration/cli/)
 
 ## Screencasts 🎦
 

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 }}

site/build_docs.py

@@ -1,87 +1,111 @@
+#!/usr/bin/env python3
+
 # Copyright (C) 2021-2022 Intel Corporation
+# Copyright (C) 2022 CVAT.ai Corporation
 #
 # SPDX-License-Identifier: MIT
 
-import os
 import shutil
 import subprocess
+import tarfile
+import tempfile
+from pathlib import Path
 
-from packaging import version
 import git
 import toml
+from packaging import version
+
+# the initial version for the documentation site
+MINIMUM_VERSION = version.Version("1.5.0")
 
-MINIMUM_VERSION='1.5.0'
 
 def prepare_tags(repo):
     tags = {}
     for tag in repo.tags:
         tag_version = version.parse(tag.name)
-        if tag_version >= version.Version(MINIMUM_VERSION) and not tag_version.is_prerelease:
+        if tag_version >= MINIMUM_VERSION and not tag_version.is_prerelease:
             release_version = (tag_version.major, tag_version.minor)
-            if not release_version in tags or tag_version > version.parse(tags[release_version].name):
+            if release_version not in tags or tag_version > version.parse(
+                tags[release_version].name
+            ):
                 tags[release_version] = tag
 
     return tags.values()
 
-def generate_versioning_config(filename, versions, url_prefix=''):
+
+def generate_versioning_config(filename, versions, url_prefix=""):
     def write_version_item(file_object, version, url):
-        file_object.write('[[params.versions]]\n')
+        file_object.write("[[params.versions]]\n")
         file_object.write('version = "{}"\n'.format(version))
         file_object.write('url = "{}"\n\n'.format(url))
 
-    with open(filename, 'w') as f:
-        write_version_item(f, 'Latest version', '{}/'.format(url_prefix))
+    with open(filename, "w") as f:
+        write_version_item(f, "Latest version", "{}/".format(url_prefix))
         for v in versions:
-            write_version_item(f, v, '{}/{}'.format(url_prefix, v))
+            write_version_item(f, v, "{}/{}".format(url_prefix, v))
+
+
+def git_checkout(tagname, repo, temp_dir):
+    subdirs = ["site/content/en/docs", "site/content/en/images"]
+
+    for subdir in subdirs:
+        shutil.rmtree(temp_dir / subdir)
+
+        with tempfile.TemporaryFile() as archive:
+            # `git checkout` doesn't work for this, as it modifies the index.
+            # `git restore` would work, but it's only available since Git 2.23.
+            repo.git.archive(tagname, "--", subdir, output_stream=archive)
+            archive.seek(0)
+            with tarfile.open(fileobj=archive) as tar:
+                tar.extractall(temp_dir)
 
-def git_checkout(tagname, cwd):
-    docs_dir = os.path.join(cwd, 'site', 'content', 'en', 'docs')
-    shutil.rmtree(docs_dir)
-    repo.git.checkout(tagname, '--', 'site/content/en/docs')
-    images_dir = os.path.join(cwd, 'site', 'content', 'en', 'images')
-    shutil.rmtree(images_dir)
-    repo.git.checkout(tagname, '--', 'site/content/en/images')
 
 def change_version_menu_toml(filename, version):
     data = toml.load(filename)
-    data['params']['version_menu'] = version
+    data["params"]["version_menu"] = version
 
-    with open(filename,'w') as f:
+    with open(filename, "w") as f:
         toml.dump(data, f)
 
+
 def generate_docs(repo, output_dir, tags):
-    def run_hugo(content_loc, destination_dir):
-        subprocess.run([ # nosec
-                'hugo',
-                '--destination',
-                destination_dir,
-                '--config',
-                'config.toml,versioning.toml',
-            ],
-            cwd=content_loc,
-        )
-
-    cwd = repo.working_tree_dir
-    content_loc = os.path.join(cwd, 'site')
-    if not os.path.exists(output_dir):
-        os.makedirs(output_dir)
-
-    generate_versioning_config(os.path.join(cwd, 'site', 'versioning.toml'), (t.name for t in tags))
-    change_version_menu_toml(os.path.join(cwd, 'site', 'versioning.toml'), 'Latest version')
-    run_hugo(content_loc, output_dir)
-
-    generate_versioning_config(os.path.join(cwd, 'site', 'versioning.toml'), (t.name for t in tags), '/..')
-    for tag in tags:
-        git_checkout(tag.name, cwd)
-        destination_dir = os.path.join(output_dir, tag.name)
-        change_version_menu_toml(os.path.join(cwd, 'site', 'versioning.toml'), tag.name)
-        os.makedirs(destination_dir)
-        run_hugo(content_loc, destination_dir)
+    repo_root = Path(repo.working_tree_dir)
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        content_loc = Path(temp_dir, "site")
+        shutil.copytree(repo_root / "site", content_loc, symlinks=True)
+
+        def run_hugo(destination_dir):
+            subprocess.run(  # nosec
+                [
+                    "hugo",
+                    "--destination",
+                    str(destination_dir),
+                    "--config",
+                    "config.toml,versioning.toml",
+                ],
+                cwd=content_loc,
+                check=True,
+            )
+
+        versioning_toml_path = content_loc / "versioning.toml"
+
+        # Handle the develop version
+        generate_versioning_config(versioning_toml_path, (t.name for t in tags))
+        change_version_menu_toml(versioning_toml_path, "develop")
+        run_hugo(output_dir)
+
+        generate_versioning_config(versioning_toml_path, (t.name for t in tags), "/..")
+        for tag in tags:
+            git_checkout(tag.name, repo, Path(temp_dir))
+            change_version_menu_toml(versioning_toml_path, tag.name)
+            run_hugo(output_dir / tag.name)
+
 
 if __name__ == "__main__":
-    repo_root = os.getcwd()
-    repo = git.Repo(repo_root)
-    output_dir = os.path.join(repo_root, 'public')
+    repo_root = Path(__file__).resolve().parents[1]
+    output_dir = repo_root / "public"
 
-    tags = prepare_tags(repo)
-    generate_docs(repo, output_dir, tags)
+    with git.Repo(repo_root) as repo:
+        tags = prepare_tags(repo)
+        generate_docs(repo, output_dir, tags)

site/config.toml

@@ -8,7 +8,7 @@ enableRobotsTXT = true
 theme = ["docsy"]
 
 # Will give values to .Lastmod etc.
-enableGitInfo = true
+enableGitInfo = false
 
 # Language settings
 contentDir = "content/en"

site/content/en/docs/contributing/_index.md

@@ -1,7 +1,7 @@
 ---
 title: 'Contributing to this project'
 linkTitle: 'Contributing'
-weight: 4
+weight: 5
 description: 'This section contains documents for CVAT developers.'
 ---
 

site/content/en/docs/contributing/rest-api-design.md

@@ -5,43 +5,4 @@ weight: 100
 description: 'Information on using the REST API scheme and principles of its design.'
 ---
 
-## REST API scheme
-
-Common scheme for our REST API is `<VERB> [namespace] <objects> <id> <action>`.
-
-- `VERB` can be `POST`, `GET`, `PATCH`, `PUT`, `DELETE`.
-- `namespace` should scope some specific functionality like `auth`, `lambda`.
-  It is optional in the scheme.
-- Typical `objects` are `tasks`, `projects`, `jobs`.
-- When you want to extract a specific object from a collection, just specify its `id`.
-- An `action` can be used to simplify REST API or provide an endpoint for entities
-  without `objects` endpoint like `annotations`, `data`, `data/meta`. Note: action
-  should not duplicate other endpoints without a reason.
-
-## Design principles
-
-- Use nouns instead of verbs in endpoint paths. For example,
-  `POST /api/tasks` instead of `POST /api/tasks/create`.
-- Accept and respond with JSON whenever it is possible
-- Name collections with plural nouns (e.g. `/tasks`, `/projects`)
-- Try to keep the API structure flat. Prefer two separate endpoints
-  for `/projects` and `/tasks` instead of `/projects/:id1/tasks/:id2`. Use
-  filters to extract necessary information like `/tasks/:id2?project=:id1`.
-  In some cases it is useful to get all `tasks`. If the structure is
-  hierarchical, it cannot be done easily. Also you have to know both `:id1`
-  and `:id2` to get information about the task.
-  _Note: for now we accept `GET /tasks/:id2/jobs` but it should be replaced
-  by `/jobs?task=:id2` in the future_.
-- Handle errors gracefully and return standard error codes (e.g. `201`, `400`)
-- Allow filtering, sorting, and pagination
-- Maintain good security practices
-- Cache data to improve performance
-- Versioning our APIs. It should be done when you delete an endpoint or modify
-  its behaviors. Versioning uses a schema with `Accept` header with vendor media type.
-
-## Links
-
-- [Best practices for REST API design](https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/)
-- [Flat vs. nested resources](https://stackoverflow.com/questions/20951419/what-are-best-practices-for-rest-nested-resources)
-- [REST API Design Best Practices for Sub and Nested Resources](https://www.moesif.com/blog/technical/api-design/REST-API-Design-Best-Practices-for-Sub-and-Nested-Resources/)
-- [A specification for building APIs in JSON](https://jsonapi.org/)
+This page was moved [here](/docs/integration/server-api/).