diff --git a/blueprints/source/conf.py b/blueprints/source/conf.py new file mode 100644 index 0000000..f99d456 --- /dev/null +++ b/blueprints/source/conf.py @@ -0,0 +1,117 @@ +# 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 = [ + 'otcdocstheme', +] + +otcdocs_auto_name = False +otcdocs_auto_version = False + +project = 'Architecture Center' +otcdocs_repo_name = 'docs/architecture-center' +# 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 = '/architecture-center/blueprints/' +otcdocs_doc_title = 'Architecture Center Blueprints' +otcdocs_doc_type = 'blueprints' +otcdocs_service_category = 'other' +otcdocs_service_title = 'Architecture Center' +otcdocs_service_type = 'ac' +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 = "Architecture Center - Architecture Center Blueprints" + + +# 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 + +# -- Options for PDF output -------------------------------------------------- +latex_documents = [ + ('index', + 'architecture-center-blueprints.tex', + u'Architecture Center - Architecture Center Blueprints', + u'OpenTelekomCloud', 'manual'), +] diff --git a/caf/source/conf.py b/caf/source/conf.py new file mode 100644 index 0000000..4a40919 --- /dev/null +++ b/caf/source/conf.py @@ -0,0 +1,117 @@ +# 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 = [ + 'otcdocstheme', +] + +otcdocs_auto_name = False +otcdocs_auto_version = False + +project = 'Architecture Center' +otcdocs_repo_name = 'docs/architecture-center' +# 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 = '/architecture-center/cloud-adoption-framework/' +otcdocs_doc_title = 'Architecture Center Cloud Adoption Framework' +otcdocs_doc_type = 'caf' +otcdocs_service_category = 'other' +otcdocs_service_title = 'Architecture Center' +otcdocs_service_type = 'ac' +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 = "Architecture Center - Architecture Center Cloud Adoption Framework" + + +# 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 + +# -- Options for PDF output -------------------------------------------------- +latex_documents = [ + ('index', + 'architecture-center-cloud-adoption-framework.tex', + u'Architecture Center - Architecture Center Cloud Adoption Framework', + u'OpenTelekomCloud', 'manual'), +] diff --git a/doc/requirements.txt b/doc/requirements.txt index a61c706..492834a 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,4 +1,11 @@ sphinx>=2.0.0,!=2.1.0 # BSD + 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 +setuptools \ 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 4612263..1d60cc7 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,75 +1,113 @@ -# -*- 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 +# 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. +# 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 -sys.path.insert(0, os.path.abspath('../..')) +extensions = [ + 'otcdocstheme', + 'otc_sphinx_directives' +] + +otcdocs_auto_name = False +otcdocs_auto_version = False + +project = 'Architecture Center' +otcdocs_repo_name = 'docs/architecture-center' +# 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 = 'Architecture Center' +otcdocs_service_type = 'ac' +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. -extensions = [ - 'sphinx.ext.autodoc', - 'otcdocstheme', -] - -# autodoc generation is a bit aggressive and a nuisance when doing heavy -# text edit cycles. -# execute "export SPHINX_DEBUG=1" in your terminal to disable # 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. -project = 'architecture-center' -copyright = '2022, Open Telekom Cloud Developers' +copyright = u'2022-present, Open Telekom Cloud' -# If true, '()' will be appended to :func: etc. cross-reference text. -add_function_parentheses = True +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +language = 'en' -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -add_module_names = True - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'native' +# 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 = '_theme' -# html_static_path = ['static'] html_theme = 'otcdocs' -# Output file base name for HTML help builder. -htmlhelp_basename = '%sdoc' % project +# 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", +} -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass -# [howto/manual]). -latex_documents = [ - ('index', - '%s.tex' % project, - '%s Documentation' % project, - 'Open Telekom Cloud Developers', 'manual'), -] +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". -# Example configuration for intersphinx: refer to the Python standard library. -#intersphinx_mapping = {'http://docs.python.org/': None} +html_title = "Architecture Center - 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'] + +# Do not include sources into the rendered results +html_copy_source = False + +# -- Options for PDF output -------------------------------------------------- +latex_documents = [] diff --git a/tox.ini b/tox.ini index 5a5506d..388e1cf 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,6 @@ [tox] minversion = 3.1 -envlist = py310,pep8 +envlist = py39,pep8 skipsdist = True ignore_basepython_conflict = True @@ -8,88 +8,166 @@ ignore_basepython_conflict = True usedevelop = True install_command = pip install {opts} {packages} deps = - -r{toxinidir}/requirements.txt + -r{toxinidir}/requirements.txt commands = stestr run {posargs} - stestr slowest + stestr slowest [testenv:pep8] commands = - doc8 doc/source README.rst + doc8 doc/source README.rst [testenv:venv] deps = - -r{toxinidir}/requirements.txt + -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 -commands = - sphinx-build -W --keep-going -b html doc/source/ doc/build/html - -[testenv:api-ref] -# This environment is called from CI scripts to test and publish -# the API Ref to docs.otc-service.com -deps = - -r{toxinidir}/requirements.txt -whitelist_externals = rm -commands = - rm -rf api-ref/build - sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html - -[testenv:api-ref-pdf-docs] -deps = {[testenv:api-ref]deps} -envdir = {toxworkdir}/api-ref -whitelist_externals = + -r{toxinidir}/doc/requirements.txt + -c https://raw.githubusercontent.com/opentelekomcloud-docs/docs-constraints/main/constraints.txt +allowlist_externals = + mkdir + cp + sh rm - make + sphinx-build commands = - rm -rf api-ref/build/pdf - sphinx-build -a -E -W -b latex api-ref/source api-ref/build/pdf - make -C api-ref/build/pdf + 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:caf]commands} + {[testenv:json-caf]commands} + {[testenv:blueprints]commands} + {[testenv:json-blueprints]commands} -[testenv:umn] -# This environment is called from CI scripts to test and publish -# the UMN to docs.otc-service.com +[testenv:docs-pdf] deps = - -r{toxinidir}/requirements.txt -whitelist_externals = rm -commands = - rm -rf umn/build - sphinx-build -W -b html -d umn/build/doctrees umn/source umn/build/html - -[testenv:umn-pdf-docs] -deps = {[testenv:umn]deps} -envdir = {toxworkdir}/umn -whitelist_externals = + {[testenv:docs]deps} + {[testenv:bindeps]deps} +allowlist_externals = rm + mkdir + wget make bash + cp commands = - rm -rf umn/build/pdf - sphinx-build -a -E -W -b latex umn/source umn/build/pdf - bash -c "for f in umn/build/pdf/*.gif; do convert $f $\{f/%gif/png\}; done || true" - bash -c "for f in umn/build/pdf/*.tex; do sed -iorig 's/\.gif//g' $f; done" - make -C umn/build/pdf + mkdir -p doc/build/pdf + {[testenv:bindeps]commands} + {[testenv:caf-pdf-docs]commands} + {[testenv:blueprints-pdf-docs]commands} -[testenv:dev-guide] -# This environment is called from CI scripts to test and publish -# the Developer Guide to docs.otc-service.com -deps = - -r{toxinidir}/requirements.txt -whitelist_externals = rm + +# HTML version +[testenv:caf] +deps = {[testenv:docs]deps} +allowlist_externals = + cp + mkdir commands = - rm -rf dev_guide/build - sphinx-build -W -b html -d dev_guide/build/doctrees dev_guide/source dev_guide/build/html + sphinx-build -W --keep-going -b html caf/source doc/build/html_temp/caf + sphinx-minify --input-directory doc/build/html_temp/caf --output-directory doc/build/html/caf + mkdir -p caf/build/html + cp -av doc/build/html/caf caf/build/html -[testenv:dev-guide-pdf-docs] -deps = {[testenv:dev-guide]deps} -envdir = {toxworkdir}/dev_guide -whitelist_externals = - rm - make +# Json version (for search) +[testenv:json-caf] +deps = {[testenv:docs]deps} +allowlist_externals = + cp + mkdir sh commands = - rm -rf dev_guide/build/pdf - sphinx-build -a -E -W -b latex dev_guide/source dev_guide/build/pdf - make -C dev_guide/build/pdf + sphinx-build -W --keep-going -b json caf/source doc/build/json/caf + # 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 caf/build/json + cp -av doc/build/json/caf caf/build/json + +# PDF version +[testenv:caf-pdf-docs] +deps = {[testenv:docs]deps} +allowlist_externals = + rm + mkdir + make + bash + cp +commands = + rm -rf caf/build/pdf + sphinx-build -W --keep-going -b latex caf/source caf/build/pdf/ + bash -c "for f in caf/build/pdf/*.gif; do convert $f $\{f/%gif/png\}; done || true" + bash -c "for f in caf/build/pdf/*.tex; do sed -iorig 's/\.gif//g' $f; done" + make -C caf/build/pdf + mkdir -p doc/build/pdf + cp caf/build/pdf/architecture-center-cloud-adoption-framework.pdf doc/build/pdf/ + + +# HTML version +[testenv:blueprints] +deps = {[testenv:docs]deps} +allowlist_externals = + cp + mkdir +commands = + sphinx-build -W --keep-going -b html blueprints/source doc/build/html_temp/blueprints + sphinx-minify --input-directory doc/build/html_temp/blueprints --output-directory doc/build/html/blueprints + mkdir -p blueprints/build/html + cp -av doc/build/html/blueprints blueprints/build/html + +# Json version (for search) +[testenv:json-blueprints] +deps = {[testenv:docs]deps} +allowlist_externals = + cp + mkdir + sh +commands = + sphinx-build -W --keep-going -b json blueprints/source doc/build/json/blueprints + # 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 blueprints/build/json + cp -av doc/build/json/blueprints blueprints/build/json + +# PDF version +[testenv:blueprints-pdf-docs] +deps = {[testenv:docs]deps} +allowlist_externals = + rm + mkdir + make + bash + cp +commands = + rm -rf blueprints/build/pdf + sphinx-build -W --keep-going -b latex blueprints/source blueprints/build/pdf/ + bash -c "for f in blueprints/build/pdf/*.gif; do convert $f $\{f/%gif/png\}; done || true" + bash -c "for f in blueprints/build/pdf/*.tex; do sed -iorig 's/\.gif//g' $f; done" + make -C blueprints/build/pdf + mkdir -p doc/build/pdf + cp blueprints/build/pdf/architecture-center-blueprints.pdf doc/build/pdf/ + + + +[testenv:bindeps] +deps = + bindep +allowlist_externals = + wget + rm + bash +commands = + rm -rf {toxinidir}/bindep.txt + rm -rf {toxinidir}/packages.txt + wget -O {toxinidir}/bindep.txt https://raw.githubusercontent.com/opentelekomcloud/otcdocstheme/main/bindep.txt + bash -c "bindep test -b -f {toxinidir}/bindep.txt > {toxinidir}/packages.txt || true" + bash -c 'if [ -s {toxinidir}/packages.txt ]; then if command -v apt &>/dev/null; then apt update && xargs apt install --no-install-recommends -y < {toxinidir}/packages.txt; fi; fi' + bash -c 'if [ -s {toxinidir}/packages.txt ]; then if command -v dnf &>/dev/null; then dnf install -y $(cat {toxinidir}/packages.txt); fi; fi' + +[doc8] +ignore = D001 +extensions = .rst, .yaml \ No newline at end of file diff --git a/zuul.yaml b/zuul.yaml index a4d00bd..107ef29 100644 --- a/zuul.yaml +++ b/zuul.yaml @@ -1,3 +1,4 @@ +--- - project: merge-mode: squash-merge default-branch: main @@ -8,4 +9,4 @@ - noop gate: jobs: - - noop + - noop \ No newline at end of file