Add SDK docs #4928

zhiltsov-max · 2022-09-09T15:05:03Z

Motivation and context

Added auth docs in API schema and SDK ApiClient/Config (fixes not able to loggin with swagger created client #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 Make various improvements to site/build_docs.py openvinotoolkit/datumaro#589)
Extracted requirements file for site

How has this been tested?

Checklist

I submit my changes into the develop branch
I have added a description of my changes into CHANGELOG file
I have updated the documentation accordingly
I have added tests to cover my changes
I have linked related issues (read github docs)
I have increased versions of npm packages if it is necessary (cvat-canvas,
cvat-core, cvat-data and cvat-ui)

License

I submit my code changes under the same MIT License that covers the project.
Feel free to contact the maintainers if that's a concern.

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

nmanovic · 2022-09-13T08:51:10Z

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

@@ -0,0 +1,31 @@
+---
+title: "Integration"


I don't like the topic. From my perspective integrations are more about collaboration with external tools (see https://voxel51.com/docs/fiftyone/integrations/index.html). The topic about our REST API, SDK, and CLI. Probably the best option is to just have 3 separate topics: REST API, SDK, CLI. Look at https://docs.labelbox.com/docs as well. I like the documentation structure.

I can see all the variants in different tools:

Labelbox: API & SDK

51: API, CLI

Label studio: Integrations (API, SDK, CLI)

Superannotate: SDK (+CLI); Integrations (with others + their dataset format)

v7: SDK; CLI; API

Probably, I agree about separate sections for SDK and CLI, but not sure about API.

Changed section name to API & SDK. The API & SDK & CLI, API, SDK & CLI variants look clumsy to my taste, and SDK can also suppose CLI by its meaning, so it shouldn't be a big loss.

site/content/en/docs/integration/backups.md

nmanovic · 2022-09-15T06:57:27Z

/check

github-actions · 2022-09-15T06:57:37Z

❌ Some checks failed
📄 See logs here

nmanovic · 2022-09-15T07:00:29Z

README.md

 - [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/)


Is it still a valid link?

I see that you have added the information below. Should we remove these 3 links?

I like to have these links. Maybe, we could provide a TOC section in the beginning? It will simplify navigation for users, because the current page is quite long. Example from Datumaro:

Then, the link will just navigate to the section below.

nmanovic · 2022-09-15T07:26:14Z

cvat-cli/src/cvat_cli/parser.py

@@ -14,6 +14,8 @@

 from .version import VERSION

+SSL_VERIFICATION_ENV_VAR = "SSL_VERIFY"


SSL_NO_VERIFY is more or less standard name for the variable (e.g., conda, git use it with a prefix)

Probably, from popular tools, only these 2 tools use variables at all:

curl: --insecure wget: --no-check-certificate pip: install ... --global http.sslVerify false apt: -o "Acquire::https::Verify-Peer=false" ... git: GIT_SSL_NO_VERIFY=true git git: config http.sslVerify "false" conda: SSL_NO_VERIFY=1 conda ... npm: config set strict-ssl false maven: -Dmaven.wagon.http.ssl.insecure=true

I decided to only use the --insecure arg instead.

nmanovic · 2022-09-15T07:27:39Z

cvat-cli/src/cvat_cli/parser.py

@@ -47,6 +49,12 @@ 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(
+        "--ssl-verify",


at the same time, the argument name is correct. I don't know why for an env variable and a command line argument the different convention is used.

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

nmanovic · 2022-09-15T08:00:41Z

site/content/en/docs/api_sdk/cli/_index.md

-weight: 29
-description: 'Guide to working with CVAT tasks in the command line interface. This section on [GitHub](https://github.com/cvat-ai/cvat/tree/develop/cvat-cli).'
+weight: 4
+description: ''


Suggested change

description: ''

description: 'Python command line interface to interact with a CVAT instance'

This description is only displayed as an extra line under the title. I'm not sure this description adds anything to the title

nmanovic · 2022-09-15T08:02:44Z

site/content/en/docs/api_sdk/sdk/_index.md

+simplify server interaction and provide additional functionality like data validation.
+
+SDK API includes 2 layers:
+- Low-level API with REST API wrappers. Located in at `cvat_sdk.api_client`. [Read more](/integration/sdk/lowlevel-api)


@zhiltsov-max , the link is broken

Fixed links

site/content/en/docs/api_sdk/sdk/developer-guide.md

Co-authored-by: Nikita Manovich <[email protected]>

nmanovic · 2022-09-15T13:12:18Z

site/content/en/docs/api_sdk/server-api/_index.md

+a command line tool, browser or a script - all interact with CVAT via HTTP requests and
+responses:
+
+![CVAT server interaction image](/images/server_api_interaction.svg)


I will prefer to have a console icon instead of a user and a list (python script?). Probably you want to ask Alexander to draw a picture for you after he comes back from vacation.

nmanovic · 2022-09-15T13:17:56Z

site/content/en/docs/api_sdk/sdk/lowlevel-api.md

+    # Here we will use models instead of a dict
+    task_data = models.DataRequest(
+        image_quality=75,
+        start_frame=2,


The parameters look strange for data that contains only 2 files.

nmanovic · 2022-09-15T13:21:52Z

site/content/en/docs/api_sdk/sdk/lowlevel-api.md

+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+_AuthApi_ | **auth_create_login** | **POST** /api/auth/login |


I don't think you want to support the table manually. It should be a reference that is generated automatically.

I agree, but it is another big task.

nmanovic · 2022-09-15T13:23:22Z

site/content/en/docs/api_sdk/sdk/lowlevel-api.md

+```python
+from cvat_sdk.api_client import ApiClient, apis
+
+api_client = ApiClient(...)


I don't think that we should describe all possible ways to use cvat_sdk.api_client. We need to show in the documentation only the recommended way.

nmanovic · 2022-09-15T13:24:36Z

site/content/en/docs/api_sdk/sdk/lowlevel-api.md

+user_model = models.User(...)
+```
+
+- About


I don't see any value in the list of strings. It should be a generated reference documenation.

nmanovic

Let's merge as is and fix comments (if you agree) in next PRs.

nmanovic · 2022-09-15T13:27:53Z

/check

github-actions · 2022-09-15T13:28:05Z

✔️ All checks completed successfully
📄 See logs here

zhiltsov-max added 9 commits September 9, 2022 11:52

Update readme

5172f49

Add requirements file for docs

cb2abd6

Move sdk developer guide

bf9e68e

Add sdk and cli integration docs

1b4cc0b

Add integration docs

19c5d83

Add rest

7fbe1de

Add pypi links

22b563f

Fixes

4cd549e

Update changelog

9fc9262

zhiltsov-max requested a review from nmanovic as a code owner September 9, 2022 15:05

zhiltsov-max added 4 commits September 9, 2022 18:36

Fix bandit warnings

3b3c9a5

Fix linter warnings

a88927a

Fix linter issues

a4b759f

Add integration components compatibility info

a81173b

nmanovic reviewed Sep 13, 2022

View reviewed changes

site/content/en/docs/contributing/rest-api-design.md Outdated Show resolved Hide resolved

nmanovic reviewed Sep 13, 2022

View reviewed changes

site/content/en/docs/integration/backups.md Outdated Show resolved Hide resolved

zhiltsov-max added 2 commits September 13, 2022 12:57

Move doc sections back, rename integration section

d120217

update changelog

d1c129f

zhiltsov-max changed the title ~~Add integration docs~~ [WIP] Add integration docs Sep 13, 2022

Update section name and readme links

61627cc

zhiltsov-max changed the title ~~[WIP] Add integration docs~~ [WIP] Add SDK docs Sep 13, 2022

zhiltsov-max added 3 commits September 13, 2022 13:09

remove rest api page from contributing

4273707

Remove cli page from manual

56d5434

Remove extra descriptions

f3e917e

zhiltsov-max changed the title ~~[WIP] Add SDK docs~~ Add SDK docs Sep 13, 2022

zhiltsov-max added 3 commits September 13, 2022 18:37

Allow unauthorized access to server api docs

ff6fa4b

Add docs for auth methods

a99713d

Allow to control SSL verification with env variable in CLI

17e7ad3

zhiltsov-max requested a review from azhavoro as a code owner September 13, 2022 16:47

Fix host schema detection test after new changes

7c79c90

nmanovic reviewed Sep 15, 2022

View reviewed changes

site/content/en/docs/api_sdk/_index.md Outdated Show resolved Hide resolved

nmanovic reviewed Sep 15, 2022

View reviewed changes

site/content/en/docs/api_sdk/sdk/developer-guide.md Outdated Show resolved Hide resolved

nmanovic reviewed Sep 15, 2022

View reviewed changes

site/content/en/docs/api_sdk/sdk/developer-guide.md Outdated Show resolved Hide resolved

zhiltsov-max and others added 6 commits September 15, 2022 11:45

Update site/content/en/docs/api_sdk/_index.md

fa39bbc

Co-authored-by: Nikita Manovich <[email protected]>

Update site/content/en/docs/api_sdk/sdk/developer-guide.md

3907d1a

Co-authored-by: Nikita Manovich <[email protected]>

Update site/content/en/docs/api_sdk/sdk/developer-guide.md

4249d7c

Co-authored-by: Nikita Manovich <[email protected]>

Fix readme links

83d7f2e

Fix links in docs

2f1f155

Use cli arg for ssl check control

d1ccd8c

nmanovic reviewed Sep 15, 2022

View reviewed changes

nmanovic approved these changes Sep 15, 2022

View reviewed changes

Remove strange parameters

8bdf579

zhiltsov-max merged commit 68375ec into develop Sep 15, 2022

bsekachev deleted the zm/update-docs branch September 23, 2022 12:04

nmanovic mentioned this pull request Nov 1, 2022

Release v2.3.0 - WebHooks #5208

Closed

nmanovic mentioned this pull request Dec 12, 2022

CVAT v2.3.0 #5452

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add SDK docs #4928

Add SDK docs #4928

zhiltsov-max commented Sep 9, 2022 •

edited

Loading

nmanovic Sep 13, 2022

zhiltsov-max Sep 13, 2022

zhiltsov-max Sep 14, 2022

nmanovic commented Sep 15, 2022

github-actions bot commented Sep 15, 2022 •

edited

Loading

nmanovic Sep 15, 2022

nmanovic Sep 15, 2022

zhiltsov-max Sep 15, 2022 •

edited

Loading

nmanovic Sep 15, 2022

zhiltsov-max Sep 15, 2022 •

edited

Loading

zhiltsov-max Sep 15, 2022 •

edited

Loading

nmanovic Sep 15, 2022

nmanovic Sep 15, 2022

zhiltsov-max Sep 15, 2022

nmanovic Sep 15, 2022

zhiltsov-max Sep 15, 2022

nmanovic Sep 15, 2022

nmanovic Sep 15, 2022

zhiltsov-max Sep 15, 2022

nmanovic Sep 15, 2022

zhiltsov-max Sep 15, 2022

nmanovic Sep 15, 2022

nmanovic Sep 15, 2022

nmanovic left a comment

nmanovic commented Sep 15, 2022

github-actions bot commented Sep 15, 2022 •

edited

Loading

		@@ -14,6 +14,8 @@

		from .version import VERSION

		SSL_VERIFICATION_ENV_VAR = "SSL_VERIFY"

	description: ''
	description: 'Python command line interface to interact with a CVAT instance'

Add SDK docs #4928

Add SDK docs #4928

Conversation

zhiltsov-max commented Sep 9, 2022 • edited Loading

Motivation and context

How has this been tested?

Checklist

License

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nmanovic commented Sep 15, 2022

github-actions bot commented Sep 15, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zhiltsov-max Sep 15, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zhiltsov-max Sep 15, 2022 • edited Loading

Choose a reason for hiding this comment

zhiltsov-max Sep 15, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nmanovic left a comment

Choose a reason for hiding this comment

nmanovic commented Sep 15, 2022

github-actions bot commented Sep 15, 2022 • edited Loading

zhiltsov-max commented Sep 9, 2022 •

edited

Loading

github-actions bot commented Sep 15, 2022 •

edited

Loading

zhiltsov-max Sep 15, 2022 •

edited

Loading

zhiltsov-max Sep 15, 2022 •

edited

Loading

zhiltsov-max Sep 15, 2022 •

edited

Loading

github-actions bot commented Sep 15, 2022 •

edited

Loading