doc: Add Client SDK examples (#1789)

Co-authored-by: Kyujin Cho <[email protected]>

.editorconfig

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

changes/1789.fix.md

@@ -0,0 +1 @@
+Add a missing `ComputeSession.start_service()` functional API in the client SDK with documentation updates

docs/README.md

@@ -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
 
@@ -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
@@ -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
@@ -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
@@ -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
@@ -126,12 +126,43 @@ Example:
 
 Please ask the docs maintainer for help.
 
-### Previewing built HTML documentation
-Simply create a nginx server which serves `_build/html` folder. For example (docker required): 
-```bash
-docker run --rm -it -v $(pwd)/_build/html:/usr/share/nginx/html -p 8000:80 nginx
-```
-Executing the command above inside `docs` folder will serve the documentation page on port 8000 (http://localhost:8000).
+
+## 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
 

docs/_static/css/customTheme.css

@@ -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 */