diff --git a/.gitignore b/.gitignore index c19e2b9..ad375bb 100644 --- a/.gitignore +++ b/.gitignore @@ -1,26 +1,30 @@ -_build/ -/AUTHORS -/ChangeLog -/dist/ -/otcdocstheme.egg-info/ -.DS_Store -*.pyc -doc/build -doc/source/BBresult -api-ref/build -.tox -/.venv -*.swp -*.log +*.DS_Store *.egg* - -# Editors +*.log +*.mo +*.pyc +*.swo +*.swp *~ - +AUTHORS +octavia_proxy-*/ +.coverage +.idea +.stestr/ +.testrepository +.tox +build +ChangeLog +dist +# Doc related +doc/build +api-ref/build +# Development environment files +.project +.pydevproject +cover # Files created by releasenotes build releasenotes/build - -# Files created by the LaTeX/PDF build -/.aux -/.fdb_latexmk -/texput.fls +.ropeproject +test.py +.vscode diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml deleted file mode 100644 index 1a96af9..0000000 --- a/.pre-commit-config.yaml +++ /dev/null @@ -1,32 +0,0 @@ -default_language_version: - python: python3 -repos: - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: 9136088a246768144165fcc3ecc3d31bb686920a # v3.3.0 - hooks: - - id: trailing-whitespace - # Replaces or checks mixed line ending - - id: mixed-line-ending - args: ['--fix', 'lf'] - exclude: '.*\.(svg)$' - # Forbid files which have a UTF-8 byte-order marker - - id: check-byte-order-marker - # Checks that non-binary executables have a proper shebang - - id: check-executables-have-shebangs - # Check for files that contain merge conflict strings. - - id: check-merge-conflict - # Check for debugger imports and py37+ breakpoint() - # calls in python source - - id: debug-statements - - id: check-yaml - files: .*\.(yaml|yml)$ - - repo: local - hooks: - - id: flake8 - name: flake8 - additional_dependencies: - - hacking>=3.0.1,<3.1.0 - language: python - entry: flake8 - files: '^.*\.py$' - exclude: '^(doc|releasenotes|tools)/.*$' diff --git a/.zuul.yaml b/.zuul.yaml deleted file mode 100644 index c373d25..0000000 --- a/.zuul.yaml +++ /dev/null @@ -1,8 +0,0 @@ -- project: - merge-mode: squash-merge - default-branch: main - vars: - # publish to blueprints container - container: "blueprints" - templates: - - publish-otc-docs-hc-pti diff --git a/bindep.txt b/bindep.txt index 5bee0c6..cf5cb86 100644 --- a/bindep.txt +++ b/bindep.txt @@ -1,5 +1 @@ -libffi-dev [platform:dpkg] -libffi-devel [platform:rpm] -libssl-dev [platform:dpkg] -openssl-devel [platform:rpm] graphviz [doc] diff --git a/doc/source/_static/css/.placeholder b/doc/best-practice/source/_static/.placeholder similarity index 100% rename from doc/source/_static/css/.placeholder rename to doc/best-practice/source/_static/.placeholder diff --git a/doc/best-practice/source/_static/css/.placeholder b/doc/best-practice/source/_static/css/.placeholder new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/_static/css/default.css b/doc/best-practice/source/_static/css/default.css similarity index 100% rename from doc/source/_static/css/default.css rename to doc/best-practice/source/_static/css/default.css diff --git a/doc/source/_static/images/ansible.svg b/doc/best-practice/source/_static/images/ansible.svg similarity index 100% rename from doc/source/_static/images/ansible.svg rename to doc/best-practice/source/_static/images/ansible.svg diff --git a/doc/source/_static/images/docker.svg b/doc/best-practice/source/_static/images/docker.svg similarity index 100% rename from doc/source/_static/images/docker.svg rename to doc/best-practice/source/_static/images/docker.svg diff --git a/doc/source/_static/images/golang.svg b/doc/best-practice/source/_static/images/golang.svg similarity index 100% rename from doc/source/_static/images/golang.svg rename to doc/best-practice/source/_static/images/golang.svg diff --git a/doc/source/_static/images/javascript.svg b/doc/best-practice/source/_static/images/javascript.svg similarity index 100% rename from doc/source/_static/images/javascript.svg rename to doc/best-practice/source/_static/images/javascript.svg diff --git a/doc/source/_static/images/k8_pod.png b/doc/best-practice/source/_static/images/k8_pod.png similarity index 100% rename from doc/source/_static/images/k8_pod.png rename to doc/best-practice/source/_static/images/k8_pod.png diff --git a/doc/source/_static/images/k8_svc.png b/doc/best-practice/source/_static/images/k8_svc.png similarity index 100% rename from doc/source/_static/images/k8_svc.png rename to doc/best-practice/source/_static/images/k8_svc.png diff --git a/doc/source/_static/images/otc.png b/doc/best-practice/source/_static/images/otc.png similarity index 100% rename from doc/source/_static/images/otc.png rename to doc/best-practice/source/_static/images/otc.png diff --git a/doc/source/_static/images/python.svg b/doc/best-practice/source/_static/images/python.svg similarity index 100% rename from doc/source/_static/images/python.svg rename to doc/best-practice/source/_static/images/python.svg diff --git a/doc/source/_static/images/rancher.svg b/doc/best-practice/source/_static/images/rancher.svg similarity index 100% rename from doc/source/_static/images/rancher.svg rename to doc/best-practice/source/_static/images/rancher.svg diff --git a/doc/source/_static/images/terraform.svg b/doc/best-practice/source/_static/images/terraform.svg similarity index 100% rename from doc/source/_static/images/terraform.svg rename to doc/best-practice/source/_static/images/terraform.svg diff --git a/doc/source/_static/images/users.png b/doc/best-practice/source/_static/images/users.png similarity index 100% rename from doc/source/_static/images/users.png rename to doc/best-practice/source/_static/images/users.png diff --git a/doc/source/_static/images/vault.png b/doc/best-practice/source/_static/images/vault.png similarity index 100% rename from doc/source/_static/images/vault.png rename to doc/best-practice/source/_static/images/vault.png diff --git a/doc/source/_static/images/zookeeper.png b/doc/best-practice/source/_static/images/zookeeper.png similarity index 100% rename from doc/source/_static/images/zookeeper.png rename to doc/best-practice/source/_static/images/zookeeper.png diff --git a/doc/source/cce_vault.rst b/doc/best-practice/source/cce_vault.rst similarity index 100% rename from doc/source/cce_vault.rst rename to doc/best-practice/source/cce_vault.rst diff --git a/doc/best-practice/source/conf.py b/doc/best-practice/source/conf.py new file mode 100644 index 0000000..c8cede6 --- /dev/null +++ b/doc/best-practice/source/conf.py @@ -0,0 +1,119 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# !!! +# This file is generated out of template in doc-exports repository. +# Beware overwriting it locally. + +import os +import sys + +extensions = [ + 'sphinx.ext.graphviz', + 'otcdocstheme', +] + +otcdocs_auto_name = False +otcdocs_auto_version = False + +project = 'Blueprints' +otcdocs_repo_name = 'docs/blueprints' +# Those variables are required for edit/bug links +otcdocs_git_fqdn = 'gitea.eco.tsi-dev.otc-service.com' +otcdocs_git_type = 'gitea' + +# Those variables are needed for indexing into OpenSearch +otcdocs_doc_environment = 'internal' +otcdocs_doc_link = '/blueprints/best-practice/' +otcdocs_doc_title = 'Best Practice' +otcdocs_doc_type = 'best-practice' +otcdocs_service_category = 'other' +otcdocs_service_title = 'Blueprints' +otcdocs_service_type = 'blueprints' +otcdocs_search_environment = 'hc_de' +otcdocs_search_url = "https://opensearch.eco.tsi-dev.otc-service.com/" + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('./')) + +# -- General configuration ---------------------------------------------------- +# https://docutils.sourceforge.io/docs/user/smartquotes.html - it does not +# what it is expected +smartquotes = False + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +# +source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +copyright = u'2022-present, Open Telekom Cloud' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +language = 'en' + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = False + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +html_theme = 'otcdocs' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + "disable_search": True, + "site_name": "Internal Documentation Portal", + "logo_url": "https://docs-int.otc-service.com", +} + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". + +html_title = "Blueprints - Best Practice" + + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Do not include sources into the rendered results +html_copy_source = False + +graphviz_output_format = 'svg' +# -- Options for PDF output -------------------------------------------------- +latex_documents = [ + ('index', + 'blueprints-best-practice.tex', + u'Blueprints - Best Practice', + u'OpenTelekomCloud', 'manual'), +] diff --git a/doc/source/dot/cce_vault_overview.dot b/doc/best-practice/source/dot/cce_vault_overview.dot similarity index 100% rename from doc/source/dot/cce_vault_overview.dot rename to doc/best-practice/source/dot/cce_vault_overview.dot diff --git a/doc/best-practice/source/index.rst b/doc/best-practice/source/index.rst new file mode 100644 index 0000000..677d01d --- /dev/null +++ b/doc/best-practice/source/index.rst @@ -0,0 +1,8 @@ +========================================== +Welcome to the documentation of Blueprints +========================================== + +.. toctree:: + :maxdepth: 1 + + cce_vault diff --git a/doc/requirements.txt b/doc/requirements.txt index 0528130..c022286 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,12 +1,10 @@ -# The order of packages is significant, because pip processes them in the order -# of appearance. Changing the order has an impact on the overall integration -# process, which may cause wedges in the gate later. -# Notes: -# reno needs openstackdocstheme which needs reno (cycle dep). -# os-api-ref needs openstackdocstheme which needs os-api-ref (cycle dep). -# Put them in here will make it clear that those are only needed for -# docs. +sphinx>=2.0.0,!=2.1.0 # BSD -sphinx==4.0.0 -otcdocstheme +otcdocstheme # Apache-2.0 + +# releasenotes reno>=3.1.0 # Apache-2.0 + +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 \ No newline at end of file diff --git a/doc/source/_static/placeholder b/doc/source/_static/placeholder new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/conf.py b/doc/source/conf.py index 23a0f06..7d2158f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,80 +1,115 @@ -# -*- coding: utf-8 -*- +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at # -# -- General configuration ------------------------------------------------ +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# !!! +# This file is generated out of template in doc-exports repository. +# Beware overwriting it locally. -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. +import os +import sys extensions = [ - 'sphinx.ext.graphviz', + 'sphinx.ext.graphviz', 'otcdocstheme', + 'otc_sphinx_directives' ] -# openstackdocstheme options +otcdocs_auto_name = False +otcdocs_auto_version = False + +project = 'Blueprints' otcdocs_repo_name = 'docs/blueprints' +# Those variables are required for edit/bug links +otcdocs_git_fqdn = 'gitea.eco.tsi-dev.otc-service.com' +otcdocs_git_type = 'gitea' + +# Those variables are needed for indexing into OpenSearch +otcdocs_doc_environment = '' +otcdocs_doc_link = '' +otcdocs_doc_title = '' +otcdocs_doc_type = '' +otcdocs_service_category = 'other' +otcdocs_service_title = 'Blueprints' +otcdocs_service_type = 'blueprints' +otcdocs_search_environment = 'hc_de' +otcdocs_search_url = "https://opensearch.eco.tsi-dev.otc-service.com/" + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('./')) + +# -- General configuration ---------------------------------------------------- +# https://docutils.sourceforge.io/docs/user/smartquotes.html - it does not +# what it is expected +smartquotes = False + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # The suffix of source filenames. source_suffix = '.rst' +# The encoding of source files. +# +source_encoding = 'utf-8' + # The master toctree document. master_doc = 'index' # General information about the project. -copyright = u'2017-2021, OpenTelekomCloud Contributors' +copyright = u'2022-present, Open Telekom Cloud' -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +language = 'en' -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = False -# -- Options for HTML output ---------------------------------------------- +# -- Options for HTML output -------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] html_theme = 'otcdocs' # Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the +# further. For a list of options available for each theme, see the # documentation. -otcdocs_auto_version = False - -html_favicon = '_static/favicon.ico' - -# To use the API Reference sidebar dropdown menu, -# uncomment the html_theme_options parameter. The theme -# variable, sidebar_dropdown, should be set to `api_ref`. -# Otherwise, the list of links for the User and Ops docs -# appear in the sidebar dropdown menu. html_theme_options = { - 'show_other_versions': False, - 'sidebar_mode': 'toctree', + "disable_search": True, + "site_name": "Internal Documentation Portal", + "logo_url": "https://docs-int.otc-service.com", } +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". + +html_title = "Blueprints - Service Based View" + + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -html_css_files = [ - 'css/default.css' -] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'native' - -templates_path = ['templates'] +# Do not include sources into the rendered results +html_copy_source = False graphviz_output_format = 'svg' - -# -- Options for LaTeX output --------------------------------------------- - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ('index', 'os-doc-blueprints.tex', u'os-doc-blueprints Documentation', - u'OpenTelekomCloud Contributors', 'manual'), -] +# -- Options for PDF output -------------------------------------------------- +latex_documents = [] diff --git a/doc/source/index.rst b/doc/source/index.rst index 32eee9c..edfc925 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,15 +1,10 @@ Blueprints ========== -Users sometimes identify use cases that can be solved in a standardized way to -save research time and effort. Blueprints are a series of best practices, -curated by the Open Telekom Cloud engineering and architecture teams. While -they are not covered directly by the `Service description -`_, they are tested and -validated recommendations from our experts. +.. directive_wrapper:: + :class: container-sbv - -.. toctree:: - :maxdepth: 1 - - cce_vault.rst + .. service_card:: + :service_type: blueprints + :environment: internal + :best-practice: Best Practices emphasize architectural principles that enhance reliability, scalability, and security. This section serves as a valuable resource for architects and developers to implement cloud solutions that align with industry best practices and maximize the benefits of the public cloud infrastructure. \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..86457e9 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,8 @@ +# The order of packages is significant, because pip processes them in the order +# of appearance. Changing the order has an impact on the overall integration +# process, which may cause wedges in the gate later. +os-api-ref>=1.4.0 # Apache-2.0 +reno>=3.1.0 # Apache-2.0 +otcdocstheme # Apache-2.0 +sphinx>=2.0.0,!=2.1.0 # BSD +oslo.i18n>=3.15.3 # Apache-2.0 \ No newline at end of file diff --git a/tox.ini b/tox.ini index 966a2db..56ad1f2 100644 --- a/tox.ini +++ b/tox.ini @@ -1,26 +1,105 @@ [tox] -minversion = 3.6.0 -envlist = docs -ignore_basepython_conflict = true +minversion = 3.1 +envlist = py39,pep8 +skipsdist = True +ignore_basepython_conflict = True [testenv] -basepython = python3 -usedevelop = true +usedevelop = True +install_command = pip install {opts} {packages} deps = - # -c{env:TOX_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/upper-constraints.txt} - -r{toxinidir}/doc/requirements.txt -sitepackages = False -whitelist_externals = - rm + -r{toxinidir}/requirements.txt +commands = stestr run {posargs} + stestr slowest + +[testenv:pep8] +commands = + doc8 doc/source README.rst [testenv:venv] +deps = + -r{toxinidir}/requirements.txt commands = {posargs} +# This env is invoked in the periodic pipeline and is therefore responsible to +# build all relevant docs at once. [testenv:docs] deps = -r{toxinidir}/doc/requirements.txt - pre-commit + -c https://raw.githubusercontent.com/opentelekomcloud-docs/docs-constraints/main/constraints.txt +allowlist_externals = + mkdir + cp + sh + rm + sphinx-build commands = - # pre-commit run -a - rm -rf doc/build/hml doc/build/doctrees - sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html + rm -rf doc/build/html doc/build/html_temp doc/build/doctrees + sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html_temp + sphinx-minify --input-directory doc/build/html_temp/ --output-directory doc/build/html + {[testenv:best-practice]commands} + {[testenv:json-best-practice]commands} + +[testenv:docs-pdf] +deps = {[testenv:docs]deps} +allowlist_externals = + rm + mkdir + make + bash + cp +commands = + mkdir -p doc/build/pdf + {[testenv:best-practice-pdf-docs]commands} + + +# HTML version +[testenv:best-practice] +deps = {[testenv:docs]deps} +allowlist_externals = + cp + mkdir +commands = + sphinx-build -W --keep-going -b html doc/best-practice/source doc/build/html_temp/best-practice + sphinx-minify --input-directory doc/build/html_temp/best-practice --output-directory doc/build/html/best-practice + mkdir -p best-practice/build/html + cp -av doc/build/html/best-practice best-practice/build/html + +# Json version (for search) +[testenv:json-best-practice] +deps = {[testenv:docs]deps} +allowlist_externals = + cp + mkdir + sh +commands = + sphinx-build -W --keep-going -b json doc/best-practice/source doc/build/json/best-practice + # Drop data useless for the search - wrap it also with sh/xargs due to bugs + # in tox + sh -c "find doc/build/json -type d -and '(' -name '_images' -or -name '_static' -or -name '_sources' ')' -print0 | xargs -0 rm -rf" + mkdir -p best-practice/build/json + cp -av doc/build/json/best-practice best-practice/build/json + +# PDF version +[testenv:best-practice-pdf-docs] +deps = {[testenv:docs]deps} +allowlist_externals = + rm + mkdir + make + bash + cp +commands = + rm -rf doc/best-practice/build/pdf + sphinx-build -W --keep-going -b latex doc/best-practice/source doc/best-practice/build/pdf/ + bash -c "for f in doc/best-practice/build/pdf/*.gif; do convert $f $\{f/%gif/png\}; done || true" + bash -c "for f in doc/best-practice/build/pdf/*.tex; do sed -iorig 's/\.gif//g' $f; done" + make -C doc/best-practice/build/pdf + mkdir -p doc/build/pdf + cp doc/best-practice/build/pdf/blueprints-best-practice.pdf doc/build/pdf/ + + + +[doc8] +ignore = D001 +extensions = .rst, .yaml \ No newline at end of file diff --git a/zuul.yaml b/zuul.yaml new file mode 100644 index 0000000..a74378a --- /dev/null +++ b/zuul.yaml @@ -0,0 +1,11 @@ +- project: + merge-mode: squash-merge + default-branch: main + templates: + - helpcenter-base-jobs + check: + jobs: + - noop + gate: + jobs: + - noop \ No newline at end of file