changing css and template to better visualize sidebar

Reviewed-by: tischrei <tino.schreiber@t-systems.com>
Co-authored-by: Hasko, Vladimir <vladimir.hasko@t-systems.com>
Co-committed-by: Hasko, Vladimir <vladimir.hasko@t-systems.com>

doc/requirements.txt

@@ -10,4 +10,5 @@
 sphinx>=4.0.0
 otcdocstheme
 reno>=3.1.0 # Apache-2.0
+# commit 7cbdf09617f6d0ac5450ab1b9e3f3ae68fc55c0e
 git+https://git@gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata.git

doc/source/_static/css/default.css

@@ -47,3 +47,12 @@
 .navigator-container .card li {
   padding: 0.2rem 1rem;
 }
+
+/* A "nice" workaround to let us keep l2 level permanently open
+ * but hide child ul's not underneath current selection.
+ * The only eventually open issue is that this way the whole child tree is 
+ * open including all subtrees.
+ */
+.docs-sidebar-toc li.toctree-l2:not(.current) > ul {
+    display: none;
+}

doc/source/_static/images/services/anti_ddos.svg

@@ -0,0 +1 @@
+<svg width="48" height="52" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" overflow="hidden"><defs><clipPath id="clip0"><rect x="675" y="337" width="48" height="52"/></clipPath></defs><g clip-path="url(#clip0)" transform="translate(-675 -337)"><path d="M719.373 346.852C717.037 345.983 712.075 344.534 709.739 343.375 704.776 340.767 702.733 339.028 700.981 337.869 700.398 337.29 699.522 337 698.646 337 698.646 337 698.646 337 698.646 337 698.646 337 698.646 337 698.646 337 697.77 337 696.894 337.29 696.019 337.869 694.267 339.028 692.516 340.767 687.553 343.375 684.925 344.534 680.255 345.983 677.627 346.852 676.168 347.432 675 348.881 675.292 350.619 675.584 355.545 677.043 365.977 680.255 372.352 683.758 379.597 693.099 385.392 696.602 387.42 697.186 388 698.062 388 698.646 388 699.23 388 699.814 388 700.398 387.42 704.193 385.392 713.242 379.597 717.037 372.352 720.248 365.977 721.416 355.545 722 350.619 722 348.881 721.124 347.432 719.373 346.852ZM714.994 371.193C712.658 375.83 707.404 380.756 699.23 385.392 698.938 385.682 698.646 385.682 698.646 385.682 698.354 385.682 698.062 385.682 698.062 385.392 689.888 380.756 684.634 375.83 682.298 371.193 679.087 364.818 677.919 353.517 677.627 350.33 677.627 349.46 678.211 349.17 678.503 349.17 679.379 348.881 679.379 348.881 679.379 348.881 682.006 347.722 686.093 346.562 688.429 345.403 693.099 343.085 695.143 341.347 696.894 340.188 697.186 339.898 697.186 339.898 697.478 339.608 697.77 339.608 698.062 339.318 698.354 339.318 698.354 339.318 698.354 339.318 698.354 339.318 698.646 339.318 698.646 339.318 698.646 339.318 698.646 339.318 698.646 339.318 698.646 339.318 699.23 339.318 699.522 339.608 699.522 339.608 699.814 339.898 700.106 339.898 700.398 340.188 702.149 341.347 704.193 343.085 708.571 345.403 710.907 346.562 714.994 347.722 717.913 348.881 718.789 349.17 718.789 349.17 718.789 349.17 718.789 349.17 719.665 349.46 719.665 350.33 719.373 353.517 718.205 364.818 714.994 371.193ZM691.64 365.688C691.64 369.455 694.851 372.642 698.646 372.642 702.441 372.642 705.36 369.455 705.36 365.688 705.36 361.92 698.646 356.125 698.646 349.75 698.646 356.125 691.64 361.92 691.64 365.688ZM701.857 360.472C703.025 362.5 704.484 364.528 704.484 365.688 704.484 368.875 701.857 371.483 698.646 371.483 695.435 371.483 692.807 368.875 692.807 365.688 692.807 364.528 693.975 362.5 695.435 360.472 696.602 358.733 697.77 356.705 698.646 354.676 699.522 356.705 700.689 358.443 701.857 360.472Z" fill="#484848" fill-rule="evenodd"/></g></svg>

doc/source/_static/images/services/rms.svg

@@ -0,0 +1 @@
+<svg id="rms_1" data-name="rms 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 44 44"><g><path d="M39.5,13.41l-14-8a3,3,0,0,0-3,0l-14,8A3,3,0,0,0,7,16V32a3,3,0,0,0,1.5,2.59l14,8a3,3,0,0,0,3,0l14-8A3,3,0,0,0,41,32V16A3,3,0,0,0,39.5,13.41Zm-1,19.45L25,40.58V28.5a1,1,0,0,0-2,0V40.58L9.5,32.86A1,1,0,0,1,9,32V16.78l10.58,5.85a1,1,0,0,0,1-1.75L9.83,15,23.51,7.13a1,1,0,0,1,1,0L38.22,15l-10.64,5.9a1,1,0,0,0,1,1.75L39,16.84V32A1,1,0,0,1,38.5,32.86Z"></path><path d="M32.5,26a3,3,0,0,0-2.2,1l-5.76-3.4V16.93a3,3,0,1,0-1,0V23.6l-5.68,3.59A3,3,0,1,0,18.5,29a3,3,0,0,0-.16-.94L24,24.46l5.7,3.37A3,3,0,0,0,29.5,29a3,3,0,1,0,3-3Zm-17,5a2,2,0,1,1,2-2A2,2,0,0,1,15.5,31ZM24,16a2,2,0,1,1,2-2A2,2,0,0,1,24,16Zm8.5,15a2,2,0,1,1,2-2A2,2,0,0,1,32.5,31Z"></path></g></svg>

doc/source/_static/images/services/vpc_ep.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 44 44"><defs><style></style></defs><title>Vpc Endpoint</title><path d="M24,2A22,22,0,1,0,46,24,22,22,0,0,0,24,2Zm0,42A20,20,0,1,1,44,24,20,20,0,0,1,24,44ZM36.5,21A3.42,3.42,0,0,0,33,24H29.5a.5.5,0,0,0-.43.24l-.1.08-5,5V18.5a.5.5,0,0,0-.93-.26l-.1.08L17.32,24l0,0H12.93a2,2,0,1,0,0,1H17.5a.5.5,0,0,0,.43-.24l.1-.08,5-5V30.5a.5.5,0,0,0,.93.26l.1-.08L29.68,25l0,0H33a3.49,3.49,0,1,0,3.45-4Zm0,5.25a1.75,1.75,0,1,1,1.75-1.75A1.76,1.76,0,0,1,36.5,26.25Z" transform="translate(-2 -2)"></path></svg>

doc/source/additional/index.rst

@@ -0,0 +1,14 @@
+Additional Resources
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   endpoints
+   glossary
+   permissions
+   Console <https://console.otc.t-systems.com>
+   Health Dashboard <https://status.otc-service.com>
+   Health Dashboard Manual <https://docs.otc.t-systems.com/status-dashboard/umn/_static/OTC_Status_Dashboard_User_Guide.pdf>
+   Enterprise Dashboard <https://enterprise-dashboard.otc-service.com>
+   Security advisory </security/index>

doc/source/developer/api.rst

@@ -3,5 +3,4 @@ REST API
 
 .. navigator::
    :class: navigator-container
-   :environment: internal
    :document_type: api-ref

doc/source/developer/api_guidelines/calling_apis/ak_sk_authentication/generating_an_ak_and_sk.rst

@@ -0,0 +1,30 @@
+.. _apig-en-api-180328005:
+
+Generating an AK and SK
+=======================
+
+1. Log in to the management console.
+
+2. Click the username and choose **My Credential** from the drop-down list.
+
+3. Click **Access Keys**.
+
+4. Click **Add Access Keys** to switch to the **Add Access Keys** page.
+
+5. Enter your login password.
+
+6. Enter the verification code sent to your mailbox or mobile phone.
+
+
+   .. note::
+
+      -  Users that are created in IAM without specifying email addresses or mobile numbers only need to enter their login passwords.
+
+      -  MyWorkplace users are not required to enter their login passwords. They can create new access keys without entering verification codes if no email addresses
+         or mobile numbers have been specified.
+
+7. Click **OK** to download the access key.
+
+   .. note::
+
+      Keep the AK/SK file confidential to prevent information leakage.

doc/source/developer/api_guidelines/calling_apis/ak_sk_authentication/index.rst

@@ -0,0 +1,56 @@
+AK/SK Authentication
+====================
+
+When you use API Gateway to send requests to underlying services, the requests must be signed using the AK and SK.
+
+.. note::
+
+   AK is a unique identifier that is associated with a secret access key; the access key ID and secret access key are used together to sign requests
+   cryptographically.
+
+   SK is a key that is used in conjunction with an access key ID to cryptographically sign requests. Signing a request identifies the sender and prevents the
+   request from being altered.
+
+The AK/SK authentication process is as follows:
+
+.. _apig-en-api-180328004__li889518531076:
+
+1. A standard request is created.
+
+2. A to-be-signed string is created using the request and other related information.
+
+.. _apig-en-api-180328004__li198402221915:
+
+3. A signature is calculated using the AK/SK and to-be-signed string.
+
+4. The generated signature is added as a header or a query parameter in the HTTP request.
+
+5. After receiving the request, API Gateway performs
+   :ref:`1 <apig-en-api-180328004__li889518531076>` to
+   :ref:`3 <apig-en-api-180328004__li198402221915>` to calculate a signature.
+
+6. The new signature is compared with the signature generated in
+   :ref:`3 <apig-en-api-180328004__li198402221915>`. If they are consistent, the request
+   is processed; otherwise, the request is rejected.
+
+:ref:`Figure 1 <apig-en-api-180328004__fig104904517537>` shows the process of calling APIs through AK/SK authentication.
+
+.. _apig-en-api-180328004__fig104904517537:
+
+.. figure:: /_static/images/api_calling_process_flow.png
+   :alt: **Figure 1** API calling process flow
+
+   **Figure 1** API calling process flow
+
+.. note::
+
+   -  If a failure occurs in any step, the failure will be returned to the client application.
+
+   -  The cached token is valid for 15 minutes by default.
+
+.. toctree::
+   :maxdepth: 1
+
+   generating_an_ak_and_sk
+   signing_a_request
+   sample_code

doc/source/developer/api_guidelines/calling_apis/ak_sk_authentication/signing_a_request.rst

@@ -0,0 +1,32 @@
+Signing a Request
+=================
+
+.. _apig-en-api-180328006__li17137133433914:
+
+1. Introduce the API Gateway signing SDK in the project.
+
+   a. Download the API Gateway signing tool from the following link:
+
+..
+
+   https://apig-demo.obs.eu-de.otc.t-systems.com/java/java-sdk-core.zip
+
+   b. Decompress the downloaded package to obtain a **.jar** file.
+
+   c. Add the decompressed **.jar** file to a project, for example, Eclipse, as a dependency package. See the following figure.
+
+   .. figure:: /_static/images/sdkdemo_properties.png
+
+2. Sign the request.
+
+..
+
+   The signing method is integrated into the **.jar** file added in
+   :ref:`1 <apig-en-api-180328006__li17137133433914>`. Before sending the request, sign
+   the requested content. The signature obtained is included in the HTTP header of the request.
+
+   For details, see :ref:`Sample Code <apig-en-api-180328008>`.
+
+   .. important::
+
+      The JDK version cannot be earlier than 1.8.

doc/source/developer/api_guidelines/calling_apis/index.rst

@@ -0,0 +1,9 @@
+Calling APIs
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   obtaining_required_information
+   token_authentication
+   ak_sk_authentication/index

doc/source/developer/api_guidelines/calling_apis/token_authentication.rst

@@ -0,0 +1,75 @@
+.. _apig-en-api-180328003:
+
+Token Authentication
+====================
+
+Scenario
+--------
+
+If API requests are authenticated using tokens, the request header must contain **X-Auth-Token** (token information).
+
+This section describes how to call an API to complete token authentication.
+
+Procedure
+---------
+
+1. Send **POST https://**\ *IAM endpoint*\ **/v3/auth/tokens** to obtain the endpoint of IAM and the region name in the message body.
+
+..
+
+   See `Regions and Endpoints <https://docs.otc.t-systems.com/en-us/endpoint/index.html>`__.
+
+   An example request is as follows:
+
+   .. note::
+
+      Replace the texts in italic with actual ones. For details, see *Identity and Access Management API Reference*.
+
+      Log in to the management console, click your username in the upper right corner, and choose **My Credential** from the drop-down list. On the **My
+      Credential** page, obtain your username, domain name, and project ID.
+
+   .. code-block:: json
+
+      {
+        "auth": {
+          "identity": {
+            "methods": [
+              "password"
+            ],
+            "password": {
+              "user": {
+                "name": "username", //Obtain your username from the My Credential page.
+                "password": "password",
+                "domain": {
+                  "name": "domainname" //Obtain your domain name from the My Credential page.
+                }
+              }
+            }
+          },
+          "scope": {
+            "project": {
+              "id": "0215ef11e49d4743be23dd97a1561e91" //Obtain your project ID from the My Credential page.
+            }
+          }
+        }
+      }
+
+.. _apig-en-api-180328003__li2615608112249:
+
+2.  Obtain the token. For details, see section "Obtaining the User Token" in the *Identity and Access Management API Reference*. If the request is successful, the
+value of the X-Subject-Token header in the response is the token.
+
+   The following figures illustrate how to use Postman to manually obtain a token.
+
+   .. figure:: /_static/images/token_authentication_example_request.png
+      :alt: **Figure 1** Example request
+
+      **Figure 1** Exmple request
+
+   .. figure:: /_static/images/obtain_x-subject-token.png
+      :alt: **Figure 2** Obtain **X-Subject-Token** from the header of the response message.
+
+      **Figure 2** Obtain **X-Subject-Token** from the header of the response message.
+
+3.  Call a service API, add the **X-Auth-Token** header with the token obtained in
+:ref:`2 <apig-en-api-180328003__li2615608112249>`.

doc/source/developer/api_guidelines/http_status_codes.rst

@@ -0,0 +1,52 @@
+HTTP Status Codes
+=================
+
+:ref:`Table 1 <apig-en-api-180328012__table11812530035>` describes common status codes.
+
+.. _apig-en-api-180328012__table11812530035:
+
+.. table:: **Table 1** User management permissions
+
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | **Return Value**                      | **Description**                                                                                          |
+   +=======================================+==========================================================================================================+
+   | 200 OK                                | The request has been processed successfully.                                                             |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 204 No Content                        | The server does not return any information.                                                              |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 400 Bad Request                       | The server failed to process the request. Possible causes include:                                       |
+   |                                       |                                                                                                          |
+   |                                       | 1. The request could not be parsed by the server due to incorrect syntax.                                |
+   |                                       |                                                                                                          |
+   |                                       | 2. Request parameters are incorrect.                                                                     |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 401 Unauthorized                      | The request requires user authentication. For example, the username and password are required.           |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 403 Forbidden                         | You are forbidden to access the requested page.                                                          |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 404 Not Found                         | The request failed because the requested resource could not be found on the server.                      |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 405 Method Not Allowed                | You are not allowed to use the method specified in the request.                                          |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 406 Not Acceptable                    | The response generated by the server could not be accepted by the client.                                |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 407 Proxy Authentication Required     | You must use the proxy server for authentication so that the request can be processed.                   |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 408 Request Timeout                   | The request timed out.                                                                                   |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 409 Conflict                          | The request could not be processed due to a conflict.                                                    |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 410 Gone                              | The requested resource is not available on the server and no known forwarding address is provided.       |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 412 Precondition Failed               | One or more conditions specified in the request header are not met when the server tests the conditions. |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 500 Internal Server Error             | The server failed to process the request due to an unexpected condition.                                 |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 501 Not Implemented                   | Failed to complete the request because the server does not support the requested function.               |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 502 Bad Gateway                       | Failed to complete the request because the server has received an invalid response.                      |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 503 Service Unavailable               | Failed to complete the request because the service is unavailable.                                       |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+
+   | 504 Gateway Timeout                   | The gateway timed out.                                                                                   |
+   +---------------------------------------+----------------------------------------------------------------------------------------------------------+

doc/source/developer/api_guidelines/index.rst

@@ -0,0 +1,10 @@
+API Usage Guidelines
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   overview
+   overview_of_rest_apis
+   calling_apis/index
+   http_status_codes

doc/source/developer/api_guidelines/overview.rst

@@ -0,0 +1,7 @@
+Overview
+========
+
+API requests sent by third-party applications to public cloud services must be authenticated using signatures.
+
+This document describes the signature procedure, provides sample code to illustrate how to use the default signer to sign requests and how to use the HTTP
+client to send requests.

doc/source/developer/index.rst

@@ -6,6 +6,7 @@ Developer
    :maxdepth: 2
 
    api
+   api_guidelines/index
    sdk
    iac
    drivers

doc/source/index.rst

@@ -11,5 +11,6 @@ Open Telekom Cloud Service Documentation
    :hidden:
 
    services
-   developer
-   links
+   developer/index
+   additional/index
+   internal/index

doc/source/internal/helpcenter_training/context.rst

@@ -0,0 +1,18 @@
+Context - Whom to address for Feedback?
+=======================================
+
+In case you have any feedback, proposals or found any issues regarding the HelpCenter 3.0, you can address them in the corresponding GitHub or Gitea repositories.
+
+Issues or feedback regarding the **internal Helpcenter** as well as new feature requests can be addressed by filing an issue on the internal **Gitea** repository under https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/issues
+
+If a documentation to a service is missing, please open a ticket on the doc-exports repository: https://gitea.eco.tsi-dev.otc-service.com/docs/doc-exports/issues
+
+If you have found any problems which affects the **production Helpcenter** please instead open an issue on **GitHub**.
+
+- In case it is a general issue, create it in the docsportal repository: https://github.com/opentelekomcloud-docs/docsportal/issues
+- If you have found anything wrong regarding a specific documentation, please open an issue on the corresponding repository under opentelekomcloud-docs. For example, on ECS you can open an issue here: https://github.com/opentelekomcloud-docs/elastic-cloud-server/issues
+
+If there is a request for completely new service or new document type (which was not yet introduced to HelpCenter 3.0) then please open an issue on the otc-metadata repository: https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata/issues
+
+
+For general questions you can write an E-Mail to the `Ecosystems Squad <mailto:dl-pbcotcdeleco@t-systems.com>`_.

doc/source/internal/helpcenter_training/difference_gitea_github.rst

@@ -0,0 +1,51 @@
+.. _difference_gitea_github:
+
+=========================
+Difference Gitea / Github
+=========================
+
+Due to the several requirements on Huawei and TSI side 2 gitops stages introduced. At first stage Huawei imports documentation to Gitea and TSI review and approve it.
+Afterwards documentation change is introduced to Github and TSI formally review it and approve.
+
+But there are few more differences which are described in the table below:
+
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| **Differences**                                    | **Gitea**                                          | **Github**                                         |
++====================================================+====================================================+====================================================+
+| Link                                               | https://gitea.eco.tsi-dev.otc-service.com/docs     | https://github.com/opentelekomcloud-docs/          |
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| Environment                                        | PREPROD                                            | PROD                                               |
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+|                                                    | internal                                           | public                                             |
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| Who can introduce changes                          | Huawei                                             | Anyone (TSI, Huawei, customer)                     |
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| Source of documentation                            | Huawei                                             | TSI+Huawei                                         |
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| Form of change                                     | Overwrite                                          | Diff                                               |
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| Portal                                             | https://docs-int.otc-service.com                   | https://docs.otc.t-systems.com                     |
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| Document types                                     | -  UMN, API, DEV, other public facing documents    | -  UMN, API, DEV, other public facing documents    |
+|                                                    |                                                    |                                                    |
+|                                                    | -  PD, HLD, CDR, other internal documents          |                                                    |
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| Stages                                             | 1. Import of the documentation change by Huawei in | 1. Review of the documentation change in target    |
+|                                                    |    doc-exports repo (html)                         |    document repository                             |
+|                                                    |                                                    |                                                    |
+|                                                    | 2. Conversion of the documentation to target       | 2. Resolve potential conflicts                     |
+|                                                    |    document repository (rst)                       |                                                    |
+|                                                    |                                                    | 3. Approve and gate documentation change in target |
+|                                                    | 3. Review of the documentation change in target    |    document repository                             |
+|                                                    |    document repository                             |                                                    |
+|                                                    |                                                    |                                                    |
+|                                                    | 4. Approve and gate documentation change in target |                                                    |
+|                                                    |    document repository                             |                                                    |
+|                                                    |                                                    |                                                    |
+|                                                    | 5. Approve and gate documentation change in        |                                                    |
+|                                                    |    doc-exports repo                                |                                                    |
+|                                                    |                                                    |                                                    |
+|                                                    | 6. Zuul automatically creates documentation change |                                                    |
+|                                                    |    in Github repo                                  |                                                    |
++----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+

doc/source/internal/helpcenter_training/faq/are_there_any_plans_to_move_other_documents_cdr_hld_and_pd_as_well_to_the_platform_so_we_can_handle_all_documents_in_one_place.rst

@@ -0,0 +1,9 @@
+=================================================================================================================================
+Are there any plans to move other documents CDR, HLD, and PD as well to the platform so we can handle all documents in one place?
+=================================================================================================================================
+
+Yes, the plan for this year is:
+
+-  Start integration of Hybrid Documentation to Help Center 3.0. Kevin Heyong has already confirmed that he initiates the talks to R&D.
+
+-  Start integration of internal Huawei documents to Help Center 3.0 (this will be a bit challenging as this sort of documents are not present in Huawei documentation system and R&D is taking care of them by their own so the only existing source of the documentation is doc word type)