docs: Reorganize and cross-link the API doc

lablup · Dec 6, 2018 · 06f8272 · 06f8272
1 parent 9320b06
commit 06f8272
Show file tree

Hide file tree

Showing 18 changed files with 86 additions and 25 deletions.
diff --git a/docs/cli.examples.rst → docs/cli/examples.rst b/docs/cli.examples.rst → docs/cli/examples.rst
@@ -1,5 +1,5 @@
-CLI Examples
-============
+Examples
+========
 
 .. note::
 

diff --git a/docs/cli/index.rst b/docs/cli/index.rst
@@ -0,0 +1,8 @@
+Command-line Interface
+======================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Table of contents
+
+   examples
diff --git a/docs/admin.rst → docs/func/admin.rst b/docs/admin.rst → docs/func/admin.rst
diff --git a/docs/agent.rst → docs/func/agent.rst b/docs/agent.rst → docs/func/agent.rst
diff --git a/docs/func/index.rst b/docs/func/index.rst
@@ -0,0 +1,13 @@
+High-level Function Reference
+=============================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Table of contents
+
+   admin
+   agent
+   kernel
+   keypair
+   manager
+   vfolder
diff --git a/docs/kernel.rst → docs/func/kernel.rst b/docs/kernel.rst → docs/func/kernel.rst
diff --git a/docs/keypair.rst → docs/func/keypair.rst b/docs/keypair.rst → docs/func/keypair.rst
diff --git a/docs/manager.rst → docs/func/manager.rst b/docs/manager.rst → docs/func/manager.rst
diff --git a/docs/vfolder.rst → docs/func/vfolder.rst b/docs/vfolder.rst → docs/func/vfolder.rst
diff --git a/docs/config.rst → docs/gsg/config.rst b/docs/config.rst → docs/gsg/config.rst
diff --git a/docs/examples.rst → docs/gsg/examples.rst b/docs/examples.rst → docs/gsg/examples.rst
diff --git a/docs/gsg/index.rst b/docs/gsg/index.rst
@@ -0,0 +1,10 @@
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Table of contents
+
+   examples
+   session
+   config
diff --git a/docs/session.rst → docs/gsg/session.rst b/docs/session.rst → docs/gsg/session.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,38 +6,58 @@
 Backend.AI Client SDK for Python
 ================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Getting Started:
+This is the documentation for the Python Client SDK which implements
+:doc:`the Backend.AI API <backendai:index>`.
 
-   examples
-   session
-   config
+Requirements
+------------
 
-.. toctree::
-   :maxdepth: 2
-   :caption: High-level Function Reference:
+Python 3.5 or higher is required.
 
-   admin
-   agent
-   kernel
-   keypair
-   manager
-   vfolder
+You can download `its official installer from python.org
+<https://www.python.org/downloads/>`_, or use a 3rd-party package/version manager
+such as `homebrew <http://brew.sh/index_ko.html>`_, `miniconda
+<http://conda.pydata.org/miniconda.html>`_, or `pyenv
+<https://github.com/pyenv/pyenv>`_.  It works on Linux, macOS, and Windows.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Low-level SDK Reference:
 
-   base
-   request
-   exceptions
+Getting Started
+---------------
+
+We recommend to create a virtual environment for isolated, unobtrusive installation
+of the client SDK library and tools.
+
+.. code-block:: console
+
+   $ python3 -m venv venv-backend-ai
+   $ source venv-backend-ai/bin/activate
+   (venv-backend-ai) $
+
+Then install the client library from PyPI.
+
+.. code-block:: console
+
+   (venv-backend-ai) $ pip install -U pip wheel setuptools
+   (venv-backend-ai) $ pip install backend.ai-client
+
+Set your API keypair as environment variables:
+
+.. code-block:: console
+
+   (venv-backend-ai) $ export BACKEND_ACCESS_KEY=AKIA...
+   (venv-backend-ai) $ export BACKEND_SECRET_KEY=...
+
+Check out more details at :doc:`gsg/config` and :doc:`gsg/examples`.
+
 
 .. toctree::
    :maxdepth: 2
-   :caption: Command-line Interface:
+   :caption: Table of contents
 
-   cli.examples
+   gsg/index
+   cli/index
+   func/index
+   lowlevel/index
 
 
 Indices and tables

diff --git a/docs/base.rst → docs/lowlevel/base.rst b/docs/base.rst → docs/lowlevel/base.rst
diff --git a/docs/exceptions.rst → docs/lowlevel/exceptions.rst b/docs/exceptions.rst → docs/lowlevel/exceptions.rst
diff --git a/docs/lowlevel/index.rst b/docs/lowlevel/index.rst
@@ -0,0 +1,10 @@
+Low-level SDK Reference
+=======================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Table of contents
+
+   base
+   request
+   exceptions
diff --git a/docs/request.rst → docs/lowlevel/request.rst b/docs/request.rst → docs/lowlevel/request.rst