Docs - Switch additional content from rst to markdown (#139)

* minor clean up in docstring * remove outdated content * docstring * Use markdown for documentation #138 * Switch some RST content to markdown #138 Co-authored-by: SimonSAMPERE <41120579+SimonSAMPERE@users.noreply.github.com>
isogeo · Dec 20, 2019 · 4951f37 · 4951f37
1 parent de30734
commit 4951f37
Show file tree

Hide file tree

Showing 12 changed files with 191 additions and 96 deletions.
diff --git a/Pipfile b/Pipfile
@@ -19,6 +19,9 @@ setuptools = "*"
 twine = "*"
 wheel = "*"
 sphinx = "*"
+sphinx-markdown-tables = "*"
+sphinx-rtd-theme = "*"
+recommonmark = "*"
 
 [packages]
 requests = ">=2.20.0"

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/docs/authentication.md b/docs/authentication.md
@@ -0,0 +1,75 @@
+# Authenticate to the API
+
+## Load API credentials from a JSON or INI file
+
+Isogeo delivers API credentials in a JSON file. Its structure depends on the kind of oAuth2 application you are developing. Please referer to the API documentation to know more about different types of oAuth2 application.
+
+For example, here is the JSON structure for a "workgroup" application:
+
+```json
+{
+"web": {
+    "client_id": "python-minimalist-sdk-test-uuid-1a2b3c4d5e6f7g8h9i0j11k12l",
+    "client_secret": "application-secret-1a2b3c4d5e6f7g8h9i0j11k12l13m14n15o16p17Q18rS",
+    "auth_uri": "https://id.api.isogeo.com/oauth/authorize",
+    "token_uri": "https://id.api.isogeo.com/oauth/token"
+    }
+}
+```
+
+The module isogeo_pysdk.utils comes with a method to load automatically credentials from JSON and INI files:
+
+```python
+# load package
+from isogeo_pysdk import Isogeo, IsogeoUtils
+
+# instanciate IsogeoUtils as utils
+utils = IsogeoUtils()
+
+# load from file
+api_credentials = utils.credentials_loader("client_secrets_group.json")
+
+# could also be:
+# api_credentials = utils.credentials_loader("client_secrets_user.json")
+# api_credentials = utils.credentials_loader("client_secrets.ini")
+
+# authenticate your client application
+isogeo = Isogeo(client_id=api_credentials.get("client_id"),
+                client_secret=api_credentials.get("client_secret")
+                )
+
+# get the token
+isogeo.connect()
+```
+
+Keys of returned dict:
+
+- auth_mode
+- client_id
+- client_secret
+- scopes
+- uri_auth
+- uri_base
+- uri_redirect
+- uri_token
+
+## Authenticate using oAuth2 Client Credentials Grant ("group application")
+
+This is the oAuth2 Backend Application flow, used by the named "group application" in Isogeo terms.
+
+Supposing secrets are stored as environment variables:
+
+```python
+# for oAuth2 Backend (Client Credentials Grant) Flow
+isogeo = Isogeo(
+    auth_mode="group",
+    client_id=environ.get("ISOGEO_API_GROUP_CLIENT_ID"),
+    client_secret=environ.get("ISOGEO_API_GROUP_CLIENT_SECRET"),
+    auto_refresh_url="{}/oauth/token".format(environ.get("ISOGEO_ID_URL")),
+    platform=environ.get("ISOGEO_PLATFORM", "qa"),
+    max_retries=1,
+)
+
+# getting a token
+isogeo.connect()
+```
diff --git a/docs/conf.py b/docs/conf.py
@@ -48,13 +48,18 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.viewcode"]
+extensions = [
+    "recommonmark",
+    "sphinx.ext.autodoc",
+    "sphinx_markdown_tables",
+    "sphinx_rtd_theme",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
 
 # The master toctree document.
 master_doc = "index"
@@ -77,12 +82,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "default"
+html_theme = "sphinx_rtd_theme"
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "IsogeoPySDK_doc"
+htmlhelp_basename = "IsogeoPySDK_Doc"
 
 
 # -- Options for Texinfo output ----------------------------------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,10 +1,5 @@
-.. Isogeo PySDK documentation master file, created by
-   sphinx-quickstart on Mon Mar 26 15:11:32 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Isogeo PySDK's documentation
-============================
+Isogeo Python SDK - Documentation
+=================================
 
 .. toctree::
    :maxdepth: 2
@@ -17,27 +12,31 @@ Isogeo PySDK's documentation
 :Source code: https://github.com/Isogeo/isogeo-api-py-minsdk/
 :Issues: https://github.com/Isogeo/isogeo-api-py-minsdk/issues
 
+.. |date| date::
+
+Updated: |date|
+
 Indices and tables
-==================
+++++++++++++++++++
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
 
-Installation
-++++++++++++
-
-.. include:: installation.rst
-
-
 Cookbook
 ++++++++
 
 .. toctree::
-    usage
+   :maxdepth: 2
+
+   installation
+   authentication
+   usage
+
+----
 
-Package modules
-+++++++++++++++
+Package modules and submodules
+++++++++++++++++++++++++++++++
 
 .. toctree::
     _apidoc/modules
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,5 @@
+# Installation
+
+```shell
+pip install isogeo-pysdk
+```
diff --git a/docs/installation.rst b/docs/installation.rst
diff --git a/docs/requirements_docs.txt b/docs/requirements_docs.txt
@@ -19,4 +19,7 @@ wheel
 requests_oauthlib
 
 # required
-Sphinx
+sphinx
+sphinx-markdown-tables  # to render markdown tables
+sphinx-rtd-theme
+recommonmark
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -103,59 +103,7 @@ With the augmented share, it's also possible to check if a metadata is present w
         print("No present").
 
 
-Load API credentials from a JSON or INI file
---------------------------------------------
 
-Isogeo delivers API credentials in a JSON file. Its structure depends on the kind of oAuth2 application you are developing. Please referer to the API documentation to know more about different types of oAuth2 application.
-
-For example, here is the JSON structure for a "workgroup" application:
-
-.. code-block:: json
-
-    {
-    "web": {
-        "client_id": "python-minimalist-sdk-test-uuid-1a2b3c4d5e6f7g8h9i0j11k12l",
-        "client_secret": "application-secret-1a2b3c4d5e6f7g8h9i0j11k12l13m14n15o16p17Q18rS",
-        "auth_uri": "https://id.api.isogeo.com/oauth/authorize",
-        "token_uri": "https://id.api.isogeo.com/oauth/token"
-        }
-    }
-
-The module isogeo_pysdk.utils comes with a method to load automatically credentials from JSON and INI files:
-
-.. code-block:: python
-
-    # load package
-    from isogeo_pysdk import Isogeo, IsogeoUtils
-
-    # instanciate IsogeoUtils as utils
-    utils = IsogeoUtils()
-
-    # load from file
-    api_credentials = utils.credentials_loader("client_secrets_group.json")
-
-    # could also be:
-    # api_credentials = utils.credentials_loader("client_secrets_user.json")
-    # api_credentials = utils.credentials_loader("client_secrets.ini")
-
-    # authenticate your client application
-    isogeo = Isogeo(client_id=api_credentials.get("client_id"),
-                    client_secret=api_credentials.get("client_secret")
-                    )
-
-    # get the token
-    isogeo.connect()
-
-Keys of returned dict:
-
-    - auth_mode
-    - client_id
-    - client_secret
-    - scopes
-    - uri_auth
-    - uri_base
-    - uri_redirect
-    - uri_token
 
 URL Builder for web applications
 --------------------------------

diff --git a/isogeo_pysdk/api/routes_contact.py b/isogeo_pysdk/api/routes_contact.py
@@ -364,6 +364,17 @@ def associate_metadata(
         :param Metadata metadata: metadata object to update
         :param Contact contact: contact model object to associate
         :param str role: role to assign to the contact
+
+        :Example:
+
+        .. code-block:: python
+
+        # retrieve a metadata
+        md = isogeo.metadata.get(METADATA_UUID)
+        # retrieve a contact
+        ctct = isogeo.contact.get(CONTACT_UUID)
+        # associate a contact to a metadata
+        isogeo.contact.associate_metadata(metadata = md, contact = ctct)
         """
         # check metadata UUID
         if not checker.check_is_uuid(metadata._id):