Skip to content

Commit

Permalink
doc: Add Client SDK examples (#1789)
Browse files Browse the repository at this point in the history
Co-authored-by: Kyujin Cho <[email protected]>
Backported-from: main
Backported-to: 23.09
  • Loading branch information
achimnol and kyujin-cho committed Dec 19, 2023
1 parent dd9d016 commit 863210b
Show file tree
Hide file tree
Showing 9 changed files with 548 additions and 225 deletions.
3 changes: 3 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ max_line_length = 100
indent_style = space
indent_size = 4

[*.md]
trim_trailing_whitespace = false

[*.rst]
max_line_length = 0
indent_style = space
Expand Down
1 change: 1 addition & 0 deletions changes/1789.fix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add a missing `ComputeSession.start_service()` functional API in the client SDK with documentation updates
61 changes: 49 additions & 12 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,24 +21,22 @@ $ git clone https://github.com/lablup/backend.ai bai-dev
$ cd ./bai-dev/docs
$ pyenv local bai-docs
$ pip install -U pip setuptools wheel
$ pip install -U \
--find-links=https://dist.backend.ai/pypi/simple/grpcio \
--find-links=https://dist.backend.ai/pypi/simple/grpcio-tools \
--find-links=https://dist.backend.ai/pypi/simple/hiredis \
--find-links=https://dist.backend.ai/pypi/simple/psycopg-binary \
-r requirements.txt
$ pip install -U -r requirements.txt
```


## Building API Reference JSON file
```console
$ ./py -m ai.backend.manager.openapi docs/manager/rest-reference/openapi.json
```
This script must be executed on behalf of the virtual environment managed by pants, not by the venv for the sphinx.
Generated OpenAPI JSON file will be located at under `manager/rest-reference/openapi.json`.


## Building HTML document

> 📌 NOTE: Please ensure that you are inside the `docs` directory and the virtualenv is activated.
> [!NOTE]
> Please ensure that you are inside the `docs` directory and the virtualenv is activated.
### Make the html version

Expand All @@ -49,15 +47,16 @@ $ make html
The compiled documentation is under `_build/html/index.html`.
You may serve it for local inspection using `python -m http.server --directory _build/html`.


## Translation

#### Generate/update pot (Portable Object Template) files
### Generate/update pot (Portable Object Template) files

```console
$ make gettext
```

#### Build po (Portable Object) files using sphinx-intl
### Build po (Portable Object) files using sphinx-intl

```console
$ sphinx-intl update -p _build/locale/ -l ko
Expand All @@ -66,7 +65,7 @@ $ sphinx-intl update -p _build/locale/ -l ko
The `.po` message files are under `locales/ko/LC_MESSAGES/`.
Edit them by filling missing translations.

#### Build HTML files with translated version
### Build HTML files with translated version

```console
$ sphinx-intl build
Expand All @@ -84,7 +83,7 @@ The compiled documentation is under `_build/latex/BackendAIDoc.pdf`.

Building PDF requires following libraries to be present on your system.

* TeX Live
* TeX Live
- ko.TeX (texlive-lang-korean)
- latexmk
* ImageMagick
Expand All @@ -93,12 +92,13 @@ Building PDF requires following libraries to be present on your system.
### Installing dependencies on macOS
1. Install MacTeX from [here](https://www.tug.org/mactex/). There are two types of MacTeX distributions; The BasicTeX one is more lightweight and MacTeX contains most of the libraries commonly used.
2. Follow [here](http://wiki.ktug.org/wiki/wiki.php/KtugPrivateRepository) (Korean) to set up KTUG repository.
3. Exceute following command to install missing dependencies.
3. Exceute following command to install missing dependencies.
```console
sudo tlmgr install latexmk tex-gyre fncychap wrapfig capt-of framed needspace collection-langkorean collection-fontsrecommended tabulary varwidth titlesec
```
4. Install both Pretendard (used for main font) and D2Coding (used to draw monospace characters) fonts on your system.


## Advanced Settings

### Managing the hierarchy of toctree (Table of Contents) of documentation
Expand Down Expand Up @@ -127,6 +127,43 @@ Example:
Please ask the docs maintainer for help.


## Preview

### The PR previews

Our ReadTheDocs bot automatically builds the HTML preview for each commit of a PR that changes
the contents of the `docs` directory.
You may simply click the link in the PR comment written by the bot.

### The HTML documentation

You may open `_build/html/index.html` from the local filesystem directly on your browser,
but the REST API reference (as of 24.03) which uses a dedicated Javascript-based viewer won't work.

To preview the full documentation including the REST API reference seamlessly, you need to run a local nginx server.

1. Create a HTTP server which serves `_build/html` folder. For example:
```bash
python -m http.server --directory _build/html 8000
```
2. Executing the command above inside `docs` folder will serve the documentation page on port 8000 (http://localhost:8000).

### Interactive GraphQL browser

You may use [GraphiQL](https://github.com/graphql/graphiql/tree/main/packages/graphiql#graphiql)
to interact and inspect the Backend.AI Manager's GraphQL API.

1. Ensure you have the access to the manager server.
The manager's *etcd* configuration should say `config/api/allow-graphql-schema-introspection` is true.
2. Run `backend.ai proxy` command of the client SDK. Depending on your setup, adjust `--bind` and `--port` options.
Use the client SDK version 21.03.7+ or 20.09.9+ at least to avoid unexpected CORS issues.
3. Copy `index.html` from https://gist.github.com/achimnol/dc9996aeffc7cf15e96478e635eb0699
4. Replace `"<proxy-address>"` with the real address (host:port) of the proxy, which can be accessed from your browser as well.
5. Run `python -m http.server` command in the directory where `index.html` is located.
6. Open the page served by the HTTP server in the previous step in your web browser.
Enjoy auto-completion and schema introspection of Backend.AI admin API!


## References for newcomers

- http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
Expand Down
171 changes: 85 additions & 86 deletions docs/_static/css/customTheme.css
Original file line number Diff line number Diff line change
Expand Up @@ -7454,89 +7454,88 @@ section {
} */

pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #767676; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #767676; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight {
background: #1E1E1E;
color: #FFF;
}
.highlight .c { color: #8f5902; font-style: italic } /* Comment */
.highlight .err { color: #a40000; border: 1px solid #ef2929 } /* Error */
.highlight .g { color: #767676 } /* Generic */
.highlight .k { color: #51B2E0; font-weight: bold } /* Keyword */
.highlight .l { color: #767676 } /* Literal */
.highlight .n { color: #767676 } /* Name */
.highlight .o { color: #ce5c00; font-weight: bold } /* Operator */
.highlight .x { color: #767676 } /* Other */
.highlight .p { color: #767676; font-weight: bold } /* Punctuation */
.highlight .ch { color: #8f5902; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #8f5902; font-style: italic } /* Comment.Preproc */
.highlight .cpf { color: #8f5902; font-style: italic } /* Comment.PreprocFile */
.highlight .c1 { color: #03B5E5; font-style: italic } /* Comment.Single */
.highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */
.highlight .gd { color: #a40000 } /* Generic.Deleted */
.highlight .ge { color: #767676; font-style: italic } /* Generic.Emph */
.highlight .ges { color: #767676; font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #ef2929 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #767676; font-style: italic } /* Generic.Output */
.highlight .gp { color: #FF9D00 } /* Generic.Prompt */
.highlight .gs { color: #767676; font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */
.highlight .kc { color: #51B2E0; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #51B2E0; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #51B2E0; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #51B2E0; font-weight: bold } /* Keyword.Pseudo */
.highlight .kr { color: #51B2E0; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #51B2E0; font-weight: bold } /* Keyword.Type */
.highlight .ld { color: #767676 } /* Literal.Date */
.highlight .m { color: #0000cf; font-weight: bold } /* Literal.Number */
.highlight .s { color: #75D100 } /* Literal.String */
.highlight .na { color: #c4a000 } /* Name.Attribute */
.highlight .nb { color: #51B2E0 } /* Name.Builtin */
.highlight .nc { color: #767676 } /* Name.Class */
.highlight .no { color: #767676 } /* Name.Constant */
.highlight .nd { color: #5c35cc; font-weight: bold } /* Name.Decorator */
.highlight .ni { color: #ce5c00 } /* Name.Entity */
.highlight .ne { color: #cc0000; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #767676 } /* Name.Function */
.highlight .nl { color: #f57900 } /* Name.Label */
.highlight .nn { color: #767676 } /* Name.Namespace */
.highlight .nx { color: #767676 } /* Name.Other */
.highlight .py { color: #767676 } /* Name.Property */
.highlight .nt { color: #51B2E0; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #767676 } /* Name.Variable */
.highlight .ow { color: #51B2E0; font-weight: bold } /* Operator.Word */
.highlight .pm { color: #767676; font-weight: bold } /* Punctuation.Marker */
.highlight .w { color: #f8f8f8 } /* Text.Whitespace */
.highlight .mb { color: #0000cf; font-weight: bold } /* Literal.Number.Bin */
.highlight .mf { color: #0000cf; font-weight: bold } /* Literal.Number.Float */
.highlight .mh { color: #0000cf; font-weight: bold } /* Literal.Number.Hex */
.highlight .mi { color: #0000cf; font-weight: bold } /* Literal.Number.Integer */
.highlight .mo { color: #0000cf; font-weight: bold } /* Literal.Number.Oct */
.highlight .sa { color: #75D100 } /* Literal.String.Affix */
.highlight .sb { color: #75D100 } /* Literal.String.Backtick */
.highlight .sc { color: #75D100 } /* Literal.String.Char */
.highlight .dl { color: #75D100 } /* Literal.String.Delimiter */
.highlight .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #75D100 } /* Literal.String.Double */
.highlight .se { color: #75D100 } /* Literal.String.Escape */
.highlight .sh { color: #75D100 } /* Literal.String.Heredoc */
.highlight .si { color: #75D100 } /* Literal.String.Interpol */
.highlight .sx { color: #75D100 } /* Literal.String.Other */
.highlight .sr { color: #75D100 } /* Literal.String.Regex */
.highlight .s1 { color: #75D100 } /* Literal.String.Single */
.highlight .ss { color: #75D100 } /* Literal.String.Symbol */
.highlight .bp { color: #3465a4 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #767676 } /* Name.Function.Magic */
.highlight .vc { color: #767676 } /* Name.Variable.Class */
.highlight .vg { color: #767676 } /* Name.Variable.Global */
.highlight .vi { color: #767676 } /* Name.Variable.Instance */
.highlight .vm { color: #767676 } /* Name.Variable.Magic */
.highlight .il { color: #0000cf; font-weight: bold } /* Literal.Number.Integer.Long */
td.linenos .normal { color: #6e7681; background-color: #0d1117; padding-left: 5px; padding-right: 5px; }
span.linenos { color: #6e7681; background-color: #0d1117; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #e6edf3; background-color: #6e7681; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #e6edf3; background-color: #6e7681; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #6e7681 }
.highlight { background: #0d1117; color: #e6edf3 }
.highlight .c { color: #8b949e; font-style: italic } /* Comment */
.highlight .err { color: #f85149 } /* Error */
.highlight .esc { color: #e6edf3 } /* Escape */
.highlight .g { color: #e6edf3 } /* Generic */
.highlight .k { color: #ff7b72 } /* Keyword */
.highlight .l { color: #a5d6ff } /* Literal */
.highlight .n { color: #e6edf3 } /* Name */
.highlight .o { color: #ff7b72; font-weight: bold } /* Operator */
.highlight .x { color: #e6edf3 } /* Other */
.highlight .p { color: #e6edf3 } /* Punctuation */
.highlight .ch { color: #8b949e; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #8b949e; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #8b949e; font-weight: bold; font-style: italic } /* Comment.Preproc */
.highlight .cpf { color: #8b949e; font-style: italic } /* Comment.PreprocFile */
.highlight .c1 { color: #8b949e; font-style: italic } /* Comment.Single */
.highlight .cs { color: #8b949e; font-weight: bold; font-style: italic } /* Comment.Special */
.highlight .gd { color: #ffa198; background-color: #490202 } /* Generic.Deleted */
.highlight .ge { color: #e6edf3; font-style: italic } /* Generic.Emph */
.highlight .ges { color: #e6edf3; font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #ffa198 } /* Generic.Error */
.highlight .gh { color: #79c0ff; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #56d364; background-color: #0f5323 } /* Generic.Inserted */
.highlight .go { color: #8b949e } /* Generic.Output */
.highlight .gp { color: #8b949e } /* Generic.Prompt */
.highlight .gs { color: #e6edf3; font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #79c0ff } /* Generic.Subheading */
.highlight .gt { color: #ff7b72 } /* Generic.Traceback */
.highlight .g-Underline { color: #e6edf3; text-decoration: underline } /* Generic.Underline */
.highlight .kc { color: #79c0ff } /* Keyword.Constant */
.highlight .kd { color: #ff7b72 } /* Keyword.Declaration */
.highlight .kn { color: #ff7b72 } /* Keyword.Namespace */
.highlight .kp { color: #79c0ff } /* Keyword.Pseudo */
.highlight .kr { color: #ff7b72 } /* Keyword.Reserved */
.highlight .kt { color: #ff7b72 } /* Keyword.Type */
.highlight .ld { color: #79c0ff } /* Literal.Date */
.highlight .m { color: #a5d6ff } /* Literal.Number */
.highlight .s { color: #a5d6ff } /* Literal.String */
.highlight .na { color: #e6edf3 } /* Name.Attribute */
.highlight .nb { color: #e6edf3 } /* Name.Builtin */
.highlight .nc { color: #f0883e; font-weight: bold } /* Name.Class */
.highlight .no { color: #79c0ff; font-weight: bold } /* Name.Constant */
.highlight .nd { color: #d2a8ff; font-weight: bold } /* Name.Decorator */
.highlight .ni { color: #ffa657 } /* Name.Entity */
.highlight .ne { color: #f0883e; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #d2a8ff; font-weight: bold } /* Name.Function */
.highlight .nl { color: #79c0ff; font-weight: bold } /* Name.Label */
.highlight .nn { color: #ff7b72 } /* Name.Namespace */
.highlight .nx { color: #e6edf3 } /* Name.Other */
.highlight .py { color: #79c0ff } /* Name.Property */
.highlight .nt { color: #7ee787 } /* Name.Tag */
.highlight .nv { color: #79c0ff } /* Name.Variable */
.highlight .ow { color: #ff7b72; font-weight: bold } /* Operator.Word */
.highlight .pm { color: #e6edf3 } /* Punctuation.Marker */
.highlight .w { color: #6e7681 } /* Text.Whitespace */
.highlight .mb { color: #a5d6ff } /* Literal.Number.Bin */
.highlight .mf { color: #a5d6ff } /* Literal.Number.Float */
.highlight .mh { color: #a5d6ff } /* Literal.Number.Hex */
.highlight .mi { color: #a5d6ff } /* Literal.Number.Integer */
.highlight .mo { color: #a5d6ff } /* Literal.Number.Oct */
.highlight .sa { color: #79c0ff } /* Literal.String.Affix */
.highlight .sb { color: #a5d6ff } /* Literal.String.Backtick */
.highlight .sc { color: #a5d6ff } /* Literal.String.Char */
.highlight .dl { color: #79c0ff } /* Literal.String.Delimiter */
.highlight .sd { color: #a5d6ff } /* Literal.String.Doc */
.highlight .s2 { color: #a5d6ff } /* Literal.String.Double */
.highlight .se { color: #79c0ff } /* Literal.String.Escape */
.highlight .sh { color: #79c0ff } /* Literal.String.Heredoc */
.highlight .si { color: #a5d6ff } /* Literal.String.Interpol */
.highlight .sx { color: #a5d6ff } /* Literal.String.Other */
.highlight .sr { color: #79c0ff } /* Literal.String.Regex */
.highlight .s1 { color: #a5d6ff } /* Literal.String.Single */
.highlight .ss { color: #a5d6ff } /* Literal.String.Symbol */
.highlight .bp { color: #e6edf3 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #d2a8ff; font-weight: bold } /* Name.Function.Magic */
.highlight .vc { color: #79c0ff } /* Name.Variable.Class */
.highlight .vg { color: #79c0ff } /* Name.Variable.Global */
.highlight .vi { color: #79c0ff } /* Name.Variable.Instance */
.highlight .vm { color: #79c0ff } /* Name.Variable.Magic */
.highlight .il { color: #a5d6ff } /* Literal.Number.Integer.Long */
Loading

0 comments on commit 863210b

Please sign in to comment.