From 8252055126fb1cac30e102b09735fc75688dba7a Mon Sep 17 00:00:00 2001
From: Luca Frosini <luca.frosini@isti.cnr.it>
Date: Wed, 21 Sep 2022 11:24:15 +0200
Subject: [PATCH] Trying to fix headers

---
 docs/index.rst | 65 ++++++++++++++++++++++++++++----------------------
 1 file changed, 37 insertions(+), 28 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 7e92be3..205bcaf 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,18 +1,20 @@
-Welcome to gCat documentation!
-=================================================
+#############################
+Welcome to gCat documentation
+#############################
 
 gCat is a RESTful application which exposes operations ...
 
 See the available REST-API on `its API docs <../api-docs/index.html>`_.
 
-Base URL
-==================
+**********
+ Base URL
+**********
 
 In the production environment, its current value is https://api.d4science.org/gcat
 
-
+*************
 Authorization
-==================
+*************
 
 D4Science adopts state-of-the-art industry standards for authentication and authorization. 
 Specifically, the implementation fully adopts `OIDC (OpenID Connect) <https://openid.net/connect>`_ for authentication and UMA 2 (User-Managed Authorization) for authorization flows. 
@@ -20,19 +22,23 @@ Specifically, the implementation fully adopts `OIDC (OpenID Connect) <https://op
 
 Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources
 
-
+*******
 Service
-==================
+*******
+
 
 You can call the methods of the Web Service by writing your own REST client application or using existing REST client plugins.
 
+=============
 HTTP Statuses
-------------------
+=============
 
-Any successful operation returns *200 OK* HTTP status code. 
+Any successful operation returns *200 OK* HTTP status code.
 The create operation returns *201 Created*. 
-Instead, the operations do not provide any content return *204 No Content*.
-A Background operation returns *202 Accepted*.
+Any Background operation returns *202 Accepted*.
+Any operation which does not provide any content return *204 No Content*.
+
+
 
 The most common error status a client can obtain are:
 
@@ -55,8 +61,10 @@ Please use this checklist before reporting an error:
 * indicate how to replicate the error;
 * indicate the time when the error occurred (this simplifies identifying the issue).
 
+============
 HTTP Methods
-------------------
+============
+
 gCat is a pure RESTful service. It uses standard HTTP Methods to perform a listing of collections and CRUD (Create Read Update Delete) operations on instances.
 
 
@@ -105,10 +113,10 @@ gCat is a pure RESTful service. It uses standard HTTP Methods to perform a listi
 	We share the same vision. For this reason, gCat does not provide server-side idempotency for DELETE and PURGE operations.
 
 .. [#Allamaraju] Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010
-
-
+ 
+ 
 About URL
-'''''''''
+*********
 
 The presented URL uses the following convention:
 
@@ -117,7 +125,7 @@ The presented URL uses the following convention:
 
 
 About Safety and Idempotency properties
-'''''''''
+***************************************
 
 * A method is *Safe* if it does not produce any side effects.
   "This does not prevent an implementation from including behaviour that is potentially harmful, that is not entirely read-only, or that causes side effects while invoking a safe method"
@@ -128,9 +136,8 @@ About Safety and Idempotency properties
 
 You can find more information about HTTP Methods at `<https://restfulapi.net/http-methods/>`_
 
-
-Uncommon HTTP Methods:
-'''''''''
+Uncommon HTTP Methods
+*********************
 
 * PATCH method allows to perform a differential update (i.e. an update which provides only the differences and not the whole new representation);
 * PURGE method is not a standard but is widely used in service which requires this action
@@ -138,8 +145,9 @@ Uncommon HTTP Methods:
   gCat provides support for this method, but to support a wider range of clients, it also provides the Purge action via *DELETE* with the additional get parameter ``purge=true``.
 
 
+============
 Content-Type
-------------------
+============
 
 Any request must contain an indication of the interesting content type.
 
@@ -159,9 +167,9 @@ The service accepts and returns only JSON objects.
  
 `Profile Collection <../api-docs/resource\_Profile.html>`_ instead can be manipulated in XML only.
 
-
+===========
 Collections
-------------------
+===========
 
 The following collections are available to any user. 
 Catalogue-Editor or above can invoke Non-safe methods only.
@@ -185,8 +193,9 @@ The following collections are available for Catalogue-Admins or above only:
 An overview of the available collections is available at `<../api-docs/index.html>`_;
 
 
+=====
 Roles
-------------------
+=====
 
 Any user has one or more roles in the catalogue.
 The VRE Manager can only assign roles. 
@@ -216,9 +225,9 @@ Catalogue-Moderator:
  .. TIP::
     Please note that not all catalogues are moderated.
 
-
+********************
 Moderated Catalogues
-==================
+********************
 
 Any catalogues can be declared as moderated.
 This means that, a Catalogue-Moderator must approve any submitted items to make them available to the other users of the catalogue.
@@ -341,9 +350,9 @@ The following table summarises the addressee of the notification for any action.
 
 
 
-
+***********
 Java Client
-==================
+***********
 
 We provide the following Java Client out-of-the-box.