rhaas3/internal-documentation
1
0
Fork 0
forked from docs/internal-documentation
Code Pull Requests Activity

Added otcdocstheme

Browse Source
This commit is contained in:
Gode, Sebastian 2024-02-16 10:14:31 +00:00
parent e1f3527bab
commit 962f1bda3f
6 changed files with 63 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/cpn/backend/index.rst
View File

@ -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/base/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#L14
5. Merge this Pull-Request and wait 10 minutes.

2
doc/source/cpn/frontend/index.rst
View File

@ -11,7 +11,7 @@ You can update the Frontend by following those steps:
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
3. Wait at least 10 minutes
4. Check whether your tag has been successfully published to the container repository: https://quay.io/repository/opentelekomcloud/circle-partner-navigator-frontend?tab=tags
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/base/kustomization.yaml#L16
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
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.

1
doc/source/index.rst
View File

@ -7,3 +7,4 @@ Internal Documentation
training/index
cpn/index
otcdocstheme/index

9
doc/source/otcdocstheme/index.rst Normal file
View File

@ -0,0 +1,9 @@
==========================
otcdocstheme Documentation
==========================
.. toctree::
:maxdepth: 1
updating_the_theme
parsed_confpy_settings

20
doc/source/otcdocstheme/parsed_confpy_settings.rst Normal file
View File

@ -0,0 +1,20 @@
================
Conf.Py Settings
================
The otcdocstheme provides a variety of configuration options which can be specified in each projects conf.py
1. repo_name = Name of the Repository which gets displayed on the left side of the HTML page
2. edit_enabled = Whether the `Edit page` button on the right side is being rendered or not
3. bug_report_enabled = Whether the `Report Documentation Bug` button on the right side is being rendered or not
4. doc_environment = `public` or `internal` to differentiate search
5. doc_link = The link to this document category, e.g. `/application-operations-management/umn/`
6. doc_title = The title of this document category, e.g. `User Guide`
7. doc_type = The type of this document, e.g. `umn`, limited to the following selection: https://github.com/opentelekomcloud/otc-sphinx-directives/blob/main/otc_sphinx_directives/service_card.py#L54
8. service_title = The service title, e.g. `Application Operations Management`
9. service_type = The service type, e.g. `aom`, limited to the following selection https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata/src/branch/main/otc_metadata/data/services
10. service_category = The service category, e.g. `application`, limited to the following selection https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata/src/branch/main/otc_metadata/data/service_categories
11. otcdocs_search_environment = Name of the search index, e.g. `hc_de`, limited to `hc_de` or `hc_swiss`
12. otcdocs_search_index = Search index wildcard name, e.g. `helpcenter-`, default: `helpcenter-`
13. otcdocs_search_url = Search URL for OpenSearch, e.g. `https://opensearch.eco.tsi-dev.otc-service.com/`

31
doc/source/otcdocstheme/updating_the_theme.rst Normal file
View File

@ -0,0 +1,31 @@
=========================
Updating the otcdocstheme
=========================
Updating the Scale Version
--------------------------
You can update the Scale version which the otcdocstheme uses by following those steps:
1. Obtain the newest Scale version from here: https://github.com/telekom/scale/releases/tag/latest
2. Look at the releasenotes and make sure there are no breaking changes
3. Download the `telekom-scale-components-x.x.x-beta.xxx.zip` file
4. Remove the `scale-components` folder inside `otcdocstheme/theme/otcdocs/static/`
5. Extract the new `scale-components` folder from the downloaded zip file to the same directory. We only need that folder and not the whole `dist` structure.
6. Render the new theme with `tox -e docs` and check for issues. Also remeber to check the sample `api-ref` documentation as well as `docsportal`
7. Open a new pull request with the changes and merge it
After that continue with the Step :ref:`new-release` to publish it to production or internal documentation.
.. _new-release:
Publishing a new Release
------------------------
After you merged changes into otcdocstheme you can proceed with releasing them to either the internal or external documentation.
1. Make sure to check whether you want your change to be only published to the internal helpcenter or to both of them.
2. Check the required version here: https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata/src/branch/main/otc_metadata/templates/doc_requirements.txt.j2#L2
3. Check the current version number of otcdocstheme https://github.com/opentelekomcloud/otcdocstheme/tags
4. Add a new tag to the latest commit of otcdocstheme and specify the version, e.g. by using `git tag 0.2.11`. Be sure to specify a higher version than the latest one. If you only want to push the changes to internal helpcenter make sure to choose a version number which is higher than the maximum allowed number for public helpcenter from step 2.
5. The next rebuild of each documentation page which happens during the night will use the updated theme