docs: move main documention inside sphinx (scaleway#279)

scaleway-bot · Aug 11, 2023 · fd7717c · fd7717c
1 parent aac9d3c
commit fd7717c
Show file tree

Hide file tree

Showing 2 changed files with 92 additions and 77 deletions.
diff --git a/README.md b/README.md
@@ -1,89 +1,18 @@
 # Scaleway Python SDK
 
-This SDK enables you to interact with Scaleway APIs.
+This SDK enables you to interact with Scaleway APIs using Python.
 
 > **Warning**
 > The project is in beta, but should be fairly stable. If you have issues using it, please [open an issue](https://github.com/scaleway/scaleway-sdk-python/issues/new).
 
 **🔗  Important links:**
 
 * [Reference documentation](https://scaleway.github.io/scaleway-sdk-python)
-* [Example projects](./examples)
 * [Developers website](https://developers.scaleway.com) (API documentation)
 
-## Installation
+## Get started
 
-This library was made using Python 3.8, it should work on the latest versions too.
-
-The SDK is available in two flavors, a synchronous and an asynchronous one. Both have the same usage, only difference is that the asynchronous library has every methods set to `async`.
-
-**Synchronous:**
-
-```sh
-pip install scaleway
-```
-
-**Asynchronous:**
-
-```sh
-pip install scaleway-async
-```
-
-## Getting Started
-
-You'll need a pair of access and secret keys to connect to Scaleway API. Please check the [documentation](https://www.scaleway.com/docs/console/my-project/how-to/generate-api-key) on how to retrieve them.
-
-**For a simpler setup**, you could retrieve the profile from the configuration file and the environment variables:
-
-```py
-from scaleway import Client
-from scaleway.registry.v1 import RegistryV1API
-
-client = Client.from_config_file_and_env()
-
-api = RegistryV1API(client)
-print(api.list_namespaces())
-```
-
-`Client.from_profile` tries to load the configuration file and the environment variables. **Environment variables take precedence over the configuration file** but this feature is configurable.
-
-**For more advanced needs**, please check the examples.
-
-## Pagination
-
-We included some pagination helpers for the methods supporting the feature. Let's take `list_namespaces()` (Registry product) as an example:
-
-Retrieve the **first page**:
-
-```py
-result = api.list_namespaces(
-    # page=1,
-)
-```
-
-Retrieve **all the pages**:
-
-```py
-namespaces = api.list_namespaces_all()
-```
-
-## Types
-
-The project is coded with Python, so don't hesitate to take advantage of it.
-
-1. All **types of a product** are stored in the `scaleway.product.version` namespace. For instance, the `Image` interface of Registry v1 can be accessed with `scaleway.registry.v1.Image`.
-
-## Logging
-
-We are using the standard Python logging library. You can configure it as you wish.
-
-```py
-import logging
-
-logger = logging.getLogger("scaleway")
-logger.addHandler(logging.StreamHandler())
-logger.setLevel(logging.DEBUG)
-```
+Please refer to the [guide](https://scaleway.github.io/scaleway-sdk-python) to get started with the SDK.
 
 ## Development
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -3,16 +3,102 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Scaleway Python SDK's documentation!
-===============================================
+#########################################
+Scaleway Python SDK documentation
+#########################################
+
+Installation
+============
+
+This library is made to work with Python 3.8 but should work on the latest versions too.
+
+The SDK is available in two flavors, a synchronous and an asynchronous one.
+
+Install from PyPI::
+
+   pip install scaleway
+
+Install from PyPI (async)::
+
+   pip install scaleway-async
+
+Initialization
+==============
+
+You'll need a pair of access and secret keys to connect to Scaleway API. Please check the `documentation <https://www.scaleway.com/en/docs/identity-and-access-management/iam/how-to/create-api-keys>`_ on how to retrieve them.
+
+:mod:`scaleway` APIs must be initialized with a :class:`scaleway.Client`. 
+
+A **minimal setup** would look like this::
+
+   from scaleway import Client
+   from scaleway.registry.v1 import RegistryV1API
+
+   client = Client(
+      access_key="SCWXXXXXXXXXXXXXXXXX",
+      secret_key="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      default_project_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      default_region="fr-par",
+      default_zone="fr-par-1",
+   )
+
+   registry_api = RegistryV1API(client)
+
+.. autofunction:: scaleway.Client
+
+For a simpler setup, you could retrieve the profile from either the configuration file or the environment variables::
+
+   from scaleway import Client
+
+   client = Client.from_config_file_and_env()  
+
+.. autofunction:: scaleway.Client.from_config_file_and_env
+
+Pagination
+==========
+
+We included some pagination helpers for the methods supporting the feature. Let's take :meth:`scaleway.registry.v1.RegistryV1API.list_namespaces` as an example:
+
+Retrieve the **first page**::
+
+   result = api.list_namespaces(
+      # page=1,
+   )
+
+.. autofunction:: scaleway.registry.v1.RegistryV1API.list_namespaces
+
+Retrieve **all the pages**::
+
+   namespaces = api.list_namespaces_all()
+
+.. autofunction:: scaleway.registry.v1.RegistryV1API.list_namespaces_all
+
+Types
+=====
+
+The project is coded with Python, so don't hesitate to take advantage of it.
+
+1. All **types of a product** are stored in the `scaleway.product.version` namespace. For instance, :class:`scaleway.registry.v1.Image`.
+
+Logging
+=======
+
+We are using the standard Python logging library. You can configure it as you wish::
+
+   import logging
+
+   logger = logging.getLogger("scaleway")
+   logger.addHandler(logging.StreamHandler())
+   logger.setLevel(logging.DEBUG)
+
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   scaleway-core
    scaleway
    scaleway-async
+   scaleway-core