small-typo fix

Reviewed-by: otcbot <otcbot@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

@@ -9,3 +9,4 @@ otc-sphinx-directives>=0.1.0
 sphinx-minify>=0.0.1 # Apache-2.0
 git+https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata.git#egg=otc_metadata
 setuptools
+gitpython

doc/source/apimon/apimon_training/workflow.rst

@@ -5,7 +5,7 @@ ApiMon Flow Process
 
 
 .. image:: training_images/apimon_data_flow.svg
-   :target: training_images/apimon_data_flow.svg
+   :target: /_images/apimon_data_flow.svg
    :alt: apimon_data_flow
 
 

doc/source/captcha_service/configuration_of_a_new_site.rst

@@ -0,0 +1,75 @@
+===========================
+Configuration of a new Site
+===========================
+
+Getting Started
+---------------
+
+1. Open the mCaptcha website: https://captcha.otc-service.com/
+2. Log-In with your credentials
+3. Click on "New Site"
+
+.. figure:: images/NewSite.png
+
+4. Click on "Advance Options" for specifying more difficulty breakpoints
+
+.. figure:: images/AdvanceOptions.png
+
+5. Specify a description, cooldown Duration and difficulty levels
+
+A good start for a contact formular would be the following paramneters:
+
+.. figure:: images/ExampleOptions.png
+
+6. Now you should be able to see your Captcha solution working by clicking on the "View Deployment" button.
+
+.. figure:: images/ViewDeployment.png
+
+
+Configuring your Frontend-Website
+---------------------------------
+
+As you now have properly configured everything on mCaptcha you will need to start including the Captcha in your frontend application.
+For this you will need to aquire your sitekey and the URL to the captcha. You can simply copy the URL from the "View Deployment" button. It should look something like this: https://captcha.otc-service.com/widget/?sitekey=RxZhnXBKERnTNRUAuNABst0v1Zvj5DZe
+
+Once you have obtained this head over to GitHub and follow the instructions to include the Captcha on your page based on your used JavaScript framework: https://github.com/mCaptcha/glue
+
+Configuring your backend
+------------------------
+
+Your backend needs to check the validity of the captcha token which the user generated.
+You can do this easily by sending an request using the generated token from the client, your sitekey and your secret key to mCaptcha.
+
+.. code:: Javascript
+
+    const postData = {
+      token: captcha_token,
+      key: captcha_sitekey,
+      secret: process.env.MCAPTCHA_SECRET
+    };
+
+    const response = await fetch(process.env.MCAPTCHA_URL + 'api/v1/pow/siteverify', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(postData)
+    });
+
+Send the request to https://captcha.otc-service.com/api/v1/pow/siteverify
+
+The response then includes a data field and must have the valid field set to true.
+
+.. code:: Javascript
+
+    if (!response.ok) {
+      throw new Error('Captcha response was not ok');
+    }
+
+    const data = await response.json();
+    if (data["valid"] !== true) {
+      return {
+        status: "fail",
+        message: "Captcha verification failed!"
+      };
+    }

doc/source/captcha_service/getting_access.rst

@@ -0,0 +1,19 @@
+=====================================
+Getting Access to the Captcha Service
+=====================================
+
+.. note::
+    Due to a current issue with mCaptcha we can't provide unqiue accounts yet and will instead provide only the required keys for setting up your captcha solution.
+
+If you need a captcha solution for one of your webpages please contact the Ecosystem Squad by writing an E-Mail to: `DL OTC Ecosystem Squad <mailto:otc_ecosystem_squad@t-systems.com>`
+Please state the following:
+
+1. Your application name
+
+.. tip::
+    For example a contact formular can take ~5s for a client to solve to prevent a lot of spam, while just checking before redirecting to a webpage should be done in less than 1s.
+
+2. Desired Average Solving time.
+
+We will provide you with a public sitekey which you will need to integrate the captcha access as well as a secret key which your backend needs for verifying whether the captcha was solved or not.
+

doc/source/captcha_service/index.rst

@@ -0,0 +1,30 @@
+===============================================
+Ecosystem Captcha Service - Powered by mCaptcha
+===============================================
+
+.. toctree::
+    :maxdepth: 1
+
+    getting_access
+    configuration_of_a_new_site
+
+General informations
+--------------------
+
+The Captcha Service is powered by mCaptcha, the used source can be found here: https://github.com/opentelekomcloud-infra/mCaptcha.
+
+If you have any issues with the service feel free to open an issue there. If it's not related to our infrastructure we will either do an upstream fix or open an upstream issue.
+
+The privacy policy can be found here: https://mcaptcha.org/privacy-policy.
+In addition to that the whole Captcha server is hosted on OTC, so no user traffic or telemetry will leave our infrastructure.
+
+How it works
+------------
+
+Compared to classic Captcha Solutions like Google's Recaptcha this service does not have any image challenges, audio challenges or any Cookie tracking.
+Instead it is using a proof-of-work solution. Each user will get a small puzzle which the browser needs to solve. This works by using WebAssembly to compute the solution using the CPU of the device from the client.
+Typically this will not take longer than around one second, although this time can be modified in the settings of mCaptcha for each unique site. In case there will be lots of traffic the puzzle will get more complex and the time for solving it will increase.
+This effectively makes attacks from outside very hard to impossible as they would need a lot of compute power to break the Captcha.
+ReCaptcha works in the same way, if you solve a lot of Captchas they will get harder and harder, just that you need to click on more and more pictures there instead of solving mathematical puzzles with compute power.
+
+For more information on how to configure mCaptcha head over to `Configuration of a new Site <configuration_of_a_new_site>`

doc/source/conf.py

@@ -16,6 +16,8 @@
 
 import os
 import sys
+from git import Repo
+from datetime import datetime
 
 extensions = [
     'otcdocstheme',
@@ -111,3 +113,9 @@ html_copy_source = False
 
 # -- Options for PDF output --------------------------------------------------
 latex_documents = []
+
+# Get the Git commit values for last updated timestamp on each page
+repo = Repo(search_parent_directories=True)
+commit = repo.head.commit
+current_commit_hash = commit.hexsha
+current_commit_time = commit.committed_datetime.strftime('%Y-%m-%d %H:%M')

doc/source/cpn/backend/index.rst

@@ -10,5 +10,5 @@ You can update the Backend by following those steps:
 1. Merge the Pull-Request
 2. Wait until the gate job has been passed
 3. Look at the Zuul-logs from the gate job. Find the line with `Successfully tagged quay.io` and remember the `:change_xx_latest` value
-4. Open a Pull-Request to adjust the kustomization config to the new tag from step 3. https://github.com/opentelekomcloud-infra/system-config/blob/main/kubernetes/circle-partner-navigator/overlays/prod/kustomization.yaml#L14
+4. Open a Pull-Request to adjust the kustomization config to the new tag from step 3. https://github.com/opentelekomcloud-infra/system-config/blob/main/kubernetes/circle-partner-navigator/overlays/prod/kustomization.yaml#L20
 5. Merge this Pull-Request and wait 10 minutes.

doc/source/cpn/frontend/index.rst

@@ -8,10 +8,9 @@ Updating the Frontend
 You can update the Frontend by following those steps:
 
 1. Merge the Pull-Request
-2. Tag the desired commit and push the tag to Github. It should be visible afterwards on this page: https://github.com/opentelekomcloud-infra/circle-partner-navigator-frontend/tags
+2. Wait at least 10 minutes
-3. Wait at least 10 minutes
+3. Check whether your tag has been successfully published to the container repository: https://quay.io/repository/opentelekomcloud/circle-partner-navigator-frontend?tab=tags
-4. Check whether your tag has been successfully published to the container repository: https://quay.io/repository/opentelekomcloud/circle-partner-navigator-frontend?tab=tags
+4. Open a Pull-Request to adjust the kustomization config to the new tag. https://github.com/opentelekomcloud-infra/system-config/blob/main/kubernetes/circle-partner-navigator/overlays/prod/kustomization.yaml#L22
-5. Open a Pull-Request to adjust the kustomization config to the new tag. https://github.com/opentelekomcloud-infra/system-config/blob/main/kubernetes/circle-partner-navigator/overlays/prod/kustomization.yaml#L16
+5. Merge this Pull-Request and wait 10 minutes.
-6. Merge this Pull-Request and wait 10 minutes.
 
 Be aware that updating the Frontend will also pull the data from the Backend again and as a result will also update the partner data on the website.

doc/source/helpcenter/hc_ops/index.rst

@@ -6,3 +6,4 @@ Helpcenter Operations
    :maxdepth: 2
 
    backstage_add_repo
+   service_based_view

doc/source/helpcenter/hc_ops/service_based_view.rst

@@ -0,0 +1,87 @@
+============================
+Service Based View knowledge
+============================
+
+This document describe necessary knowledge about our Service Based View (SVB)
+which is the landing page for the specific service. There you have a short
+description of the service and you get all the links for the service
+documents.
+
+Service Based View Code Snippets
+--------------------------------
+
+The following Code Snippets represents the necessary information which is
+needed that SVB can run properly.
+
+Internal SVB Code Snippet
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code::
+
+    Cloud Container Engine
+    ======================
+
+    CCE provides highly scalable, high-performance, enterprise-class Kubernetes clusters. It supports native Kubernetes applications, tools and easy setup of container runtime environment.
+
+    .. directive_wrapper::
+      :class: container-sbv
+
+      .. service_card::
+          :service_type: cce
+          :environment: internal
+          :umn: Describes the basic concepts, functions, key terms, best practices, FAQs and steps for quickly creating clusters and containerized applications.
+          :api-ref: Describes the APIs provided by CCE including the functions, parameters, and examples of each API.
+          :best-practice: To use Cloud Container Engine more securely, reliably, flexibly, and efficiently, you are advised to follow the following best practices.
+
+    Documents registration under: `otc_metadata/data/documents <https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata/src/branch/main/otc_metadata/data/documents>`_
+
+
+Public SVB Code Snippet
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code::
+
+    Cloud Container Engine
+    ======================
+
+    CCE provides highly scalable, high-performance, enterprise-class Kubernetes clusters. It supports native Kubernetes applications, tools and easy setup of container runtime environment.
+
+    .. directive_wrapper::
+      :class: container-sbv
+
+      .. service_card::
+          :service_type: cce
+          :umn: Describes the basic concepts, functions, key terms, best practices, FAQs and steps for quickly creating clusters and containerized applications.
+          :api-ref: Describes the APIs provided by CCE including the functions, parameters, and examples of each API.
+          :best-practice: To use Cloud Container Engine more securely, reliably, flexibly, and efficiently, you are advised to follow the following best practices.
+
+    Documents registration under: `otc_metadata/data/documents <https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata/src/branch/main/otc_metadata/data/documents>`_
+
+Possible Document Names
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The following document short names can be used to reference specific document types which are listed in the `Helpcenter Metadata <https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata>`_ .
+New document types can be requested by creating an issue under https://github.com/opentelekomcloud-docs/docsportal/issues or get in contact
+with Ecosystem Squad.
+
+* api-ref
+* blueprints
+* caf
+* dev
+* image-creation-guide
+* tool-guide
+* mycredential
+* public-images
+* sdk-ref
+* operation-guide
+* operation-guide-lts
+* parallel-file-system
+* permissions-configuration-guide
+* permissions
+* swiftapi
+* s3api
+* umn
+* umn2
+* best-practice
+* sqlreference
+* guidelines

doc/source/helpcenter/helpcenter_training/faq/how_to_update_a_component_page.rst

@@ -0,0 +1,94 @@
+============================
+How to update component page
+============================
+
+**Goal**
+
+Mark service as depricated
+
+.. image:: faq_images/storage_component_overview2.png
+   :target: faq_images/storage_component_overview2.png
+   :alt: storage_component_overview
+
+
+1)**Create fork on github**
+
+You need to create fork only in case  you don’t have existing  already
+
+.. image:: faq_images/create_github_fork_1.png
+   :target: faq_images/create_github_fork_1.png
+   :alt: create_fork_1
+
+Choose your name as owner
+
+.. image:: faq_images/create_github_fork_2.png
+   :target: faq_images/create_github_fork_2.png
+   :alt: create_fork_2
+
+2)**In case you have existing fork**
+
+You need to sync your fork with main. Then go to branches.
+
+.. image:: faq_images/github_sync_fork.png
+   :target: faq_images/github_sync_fork.png
+   :alt: sync_fork
+
+3)**Create new branch**
+
+.. image:: faq_images/github_new_branch.png
+   :target: faq_images/github_new_branch.png
+   :alt: new_branch
+
+Add new branch name:
+
+.. image:: faq_images/github_new_branch2.png
+   :target: faq_images/github_new_branch2.png
+   :alt: new_branch2
+
+4)**Edit index.rst**
+
+.. image:: faq_images/edit_index_rst.png
+   :target: faq_images/edit_index_rst.png
+   :alt: edit_index.rst
+
+5)**Edit conf.py **
+
+.. image:: faq_images/edit_conf_py.png
+   :target: faq_images/edit_conf_py.png
+   :alt: edit_conf_py
+
+6)**Commit changes**
+
+Once you finish with editing of pages click commit changes.
+
+.. image:: faq_images/commit_changes.png
+   :target: faq_images/commit_changes.png
+   :alt: commit_changes
+
+7)**Compare & pull request**
+
+.. image:: faq_images/compare_pull_request.png
+   :target: faq_images/compare_pull_request.png
+   :alt: compare_changes
+
+8)**Comparing changes**
+
+Check correct source and target pull request and branch. Then create pull request.
+
+.. image:: faq_images/compare_changes.png
+   :target: faq_images/compare_changes.png
+   :alt: compare_changes2
+
+9)**Wait for checks, approve and gate**
+
+.. image:: faq_images/check_approve_gate.png
+   :target: faq_images/check_approve_gate.png
+   :alt: check_approve_gate
+
+10)**Delete branch**
+
+After successful merge delete branch.
+
+.. image:: faq_images/delete_branch.png
+   :target: faq_images/delete_branch.png
+   :alt: delete_branch

doc/source/helpcenter/helpcenter_training/faq/how_to_update_a_landing_page.rst

@@ -0,0 +1,89 @@
+=============================
+How to update landing page
+=============================
+
+**Goal**
+
+Mark service as depricated
+
+.. image:: faq_images/storage_component_overview.png
+   :target: faq_images/storage_component_overview.png
+   :alt: storage_component_overview
+
+1)**Create fork on gitea**
+
+You need to create fork only in case  you don’t have existing  already
+
+.. image:: faq_images/infra_otc_metadata.png
+   :target: faq_images/infra_otc_metadata.png
+   :alt: infra_otc_metadata
+
+https://gitea.eco.tsi-dev.otc-service.com/marmulle/otc-metadata/src/branch/main/otc_metadata/data/documents
+
+2)**Sync fork**
+
+Sync work with main currently do not support sync in console and you need to do it manually.
+
+- you need to configure .ssh/config.ssh/config
+
+.. code-block:: text
+
+   Host gitea.eco.tsi-dev.otc-service.com
+   User git
+   Port 2222
+   HostName gitea.eco.tsi-dev.otc-service.com
+   IdentityFile ~/.ssh/id_rsa
+
+You should be able to ssh gitea and get You've successfully authenticated  message.
+
+.. code-block:: text
+
+ ssh gitea.eco.tsi-dev.otc-service.com
+
+Clone your branch, not main:
+
+.. code-block:: text
+
+   git clone ssh://git@gitea.eco.tsi-dev.otc-service.com:2222/marmulle/otc-metadata.git
+
+Then follow instructions to recover fork: https://gitea.eco.tsi-dev.otc-service.com/docs/doc-exports/wiki/Recovering-Fork
+
+3)**Update necessary file**
+
+In this case I was updating obs-swiftapi.yaml located in https://gitea.eco.tsi-dev.otc-service.com/marmulle/otc-metadata/src/branch/main/otc_metadata/data/documents
+
+4)**Propose file changes**
+
+After update file propose file changes. Name of branch or pull request should be as short as possible,but meaningful.
+
+.. image:: faq_images/propose_file_change.png
+   :target: faq_images/propose_file_change.png
+   :alt: faq_file_change
+
+5)**Create new pull request**
+
+Change destination branch into infra:main and click New Pull Request.
+
+.. image:: faq_images/gitea_new_pull_request.png
+   :target: faq_images/gitea_new_pull_request.png
+   :alt: gitea_new_pull_request
+
+Change destination branch into infra:main and click New Pull Request
+
+.. image:: faq_images/gitea_new_pull_request2.png
+   :target: faq_images/gitea_new_pull_request2.png
+   :alt: gitea_new_pull_request2
+
+Once again -  New Pull Request
+
+.. image:: faq_images/gitea_new_pull_request3.png
+   :target: faq_images/gitea_new_pull_request3.png
+   :alt: gitea_new_pull_request3
+
+6)**New pull request  approve, gate**
+
+.. image:: faq_images/gitea_new_pull_request_approve_gate.png
+   :target: faq_images/gitea_new_pull_request_approve_gate.png
+   :alt: gitea_new_pull_request_approve_gate
+
+7)**Delete branch**

doc/source/helpcenter/helpcenter_training/faq/index.rst

@@ -28,3 +28,5 @@ Frequently Asked Questions
    how_and_where_should_we_submit_bugs_when_the_documentation_url_is_wrong_the_link_is_not_working
    where_should_we_check_whether_a_document_related_bug_exists_or_not_for_our_components_if_a_customer_opens_it_or_it_is_coming_from_another_squad
    how_to_create_a_gitea_account
+   how_to_update_a_component_page
+   how_to_update_a_landing_page

doc/source/helpcenter/helpcenter_training/introduction.rst

@@ -2,36 +2,37 @@
 Introduction
 ============
 
-The HelpCenter3.0 is Open Telekom Cloud product developed by Ecosystem squad introducing new approach in the documentation management.
+The Helpcenter 3 (HC3) is an Open Telekom Cloud product developed by the Ecosystem Squad introducing
-In order to improve documentation exchange between delivery partners and the TSI a new documentation platform and processes
+a new approach in documentation management. It improves the documentation exchange between
-based on GitOps are introduced with following benefits:
+delivery partners and the service squads of the Open Telekom Cloud. The documentation
+platform comes with processes based on GitOps and introduces the following features and benefits:
 
--  Openness
+-  Openness,
--  Transparency
+-  Transparency,
--  Comprehensive review capabilities
+-  Comprehensive review capabilities,
--  Full control during the documentation lifecycle
+-  Full control during the documentation lifecycle, and
--  Documentation as a source code
+-  Documentation as source code.
 
-The target of the new platform is to store and maintain all documents in Git. This provides benefits of precise identification of changes
+The target of the platform is to store and maintain all documents in Git. This provides benefits of precise identification of changes
 and preventing undesired versions to be published. The process is heavily streamlined. Once, those changes are approved and merged,
 the connected pipelines ensure that the documentation is published fully automated which eases the document auditing and enables users
 to see the complete history of changes tracked by git itself.
 
 .. figure:: /_static/images/helpcenter_gitops.png
 
-Solution is completely open source based and HLD is described at https://docs.otc-service.com/system-config/docsportal.html
+Solution is based on open source components. Its HLD is described at https://docs.otc-service.com/system-config/docsportal.html
-Implementation is based on:
+The implementation is based on these building blocks:
 
--  Restructured Text (RST) as source documentation format
+-  Restructured Text (RST) as source documentation format,
--  Gitea/Github as a repository
+-  Gitea/Github as a repository,
--  Zuul as a CI/CD engine for workflows
+-  Zuul as a CI/CD engine for workflows,
--  Sphinx as a documentation rendering framework (HTML/PDF/...
+-  Sphinx as a documentation rendering framework creating for example HTML or PDF documents,
--  OpenSearch as a search engine
+-  OpenSearch as a search engine,
--  Swift object storage as a storage for documentation
+-  Swift object storage as a storage for documentation,
--  Pandoc as a documentation converter
+-  Pandoc as a documentation converter, and
--  OTC Infrastructure (ECS, CCE, ELB, ...)
+-  a lot of OTC Infrastructure (ECS, CCE, ELB, ...)
 
-HC3.0 comes with the following features:
+HC3 comes with following features:
 
 -  Support of UMN, API, DEV and other public facing documents
 -  PROD and PREPROD documentation portal:

doc/source/index.rst

@@ -6,7 +6,9 @@ Internal Documentation
    :maxdepth: 1
 
    APImon <apimon/index>
+   Captcha Service <captcha_service/index>
    Status Dashboard <status_dashboard/index>
    Helpcenter <helpcenter/index>
    Circle Partner Navigator <cpn/index>
    otcdocstheme <otcdocstheme/index>
+   OTC Terraform Provider <terraform/index>