adding description for best practice

Reviewed-by: Gode, Sebastian <sebastian.gode@t-systems.com>
Co-authored-by: Hasko, Vladimir <vladimir.hasko@t-systems.com>
Co-committed-by: Hasko, Vladimir <vladimir.hasko@t-systems.com>

api-ref/source/conf.py

@@ -18,7 +18,7 @@ import os
 import sys
 
 extensions = [
-    'otcdocstheme'
+    'otcdocstheme',
 ]
 
 otcdocs_auto_name = False
@@ -30,6 +30,17 @@ otcdocs_repo_name = 'docs/web-application-firewall-dedicated'
 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 = '/web-application-firewall-dedicated/api-ref/'
+otcdocs_doc_title = 'API Reference'
+otcdocs_doc_type = 'api-ref'
+otcdocs_service_category = 'security-services'
+otcdocs_service_title = 'Dedicated Web Application Firewall'
+otcdocs_service_type = 'wafd'
+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.

doc/best-practice/source/index.rst

@@ -0,0 +1,3 @@
+==================================================================
+Welcome to the documentation of web-application-firewall-dedicated
+==================================================================

doc/requirements.txt

@@ -1,4 +1,7 @@
 sphinx>=2.0.0,!=2.1.0 # BSD
 otcdocstheme # Apache-2.0
 # releasenotes
-reno>=3.1.0 # Apache-2.0
+reno>=3.1.0 # Apache-2.0
+
+otc-sphinx-directives>=0.1.0
+git+https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata.git#egg=otc_metadata

doc/source/index.rst

@@ -0,0 +1,15 @@
+Dedicated Web Application Firewall
+==================================
+
+Web Application Firewall (WAF) keeps web services stable and secure. It examines all HTTP and HTTPS requests to detect and block the following attacks: Structured Query Language (SQL) injection, cross-site scripting (XSS), webshells, command and code injections, file inclusion, sensitive file access, third-party vulnerability exploits, Challenge Collapsar (CC) attacks, malicious crawlers, and cross-site request forgery (CSRF).
+
+
+.. directive_wrapper::
+   :class: container-sbv
+
+   .. service_card::
+      :environment: internal
+      :service_type: wafd
+      :umn: This document helps you know about the Web Application Firewall (Dedicated) and guide you on how to use the service.
+      :api-ref: This document describes application programming interfaces (APIs) of the Web Application Firewall (Dedicated) and provides API parameter description and example values.
+      :best-practice: To use Web Application Firewall (Dedicated) more securely, reliably, flexibly, and efficiently, you are advised to follow the following best practices.

tox.ini

@@ -29,9 +29,15 @@ allowlist_externals =
   mkdir
   cp
   sh
+  rm
+  sphinx-build
 commands =
+  rm -rf doc/build/html doc/build/doctrees
+  sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
   {[testenv:api-ref]commands}
   {[testenv:json-api-ref]commands}
+  {[testenv:best-practice]commands}
+  {[testenv:json-best-practice]commands}
   {[testenv:umn]commands}
   {[testenv:json-umn]commands}
 
@@ -46,6 +52,7 @@ allowlist_externals =
 commands =
   mkdir -p doc/build/pdf
   {[testenv:api-ref-pdf-docs]commands}
+  {[testenv:best-practice-pdf-docs]commands}
   {[testenv:umn-pdf-docs]commands}
 
 
@@ -94,6 +101,47 @@ commands =
   cp api-ref/build/pdf/wafd-api-ref.pdf doc/build/pdf/
 
 
+# HTML version
+[testenv:best-practice]
+deps = -r{toxinidir}/doc/requirements.txt
+allowlist_externals =
+  cp
+  mkdir
+commands =
+  sphinx-build -W --keep-going -b html doc/best-practice/source doc/build/html/best-practice
+
+# Json version (for search)
+[testenv:json-best-practice]
+deps = -r{toxinidir}/doc/requirements.txt
+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"
+
+# PDF version
+[testenv:best-practice-pdf-docs]
+deps = -r{toxinidir}/doc/requirements.txt
+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/wafd-best-practice.pdf doc/build/pdf/
+
+
 # HTML version
 [testenv:umn]
 deps = -r{toxinidir}/doc/requirements.txt
@@ -138,3 +186,8 @@ commands =
   mkdir -p doc/build/pdf
   cp umn/build/pdf/wafd-umn.pdf doc/build/pdf/
 
+
+
+[doc8]
+ignore = D001
+extensions = .rst, .yaml

umn/source/conf.py

@@ -18,7 +18,7 @@ import os
 import sys
 
 extensions = [
-    'otcdocstheme'
+    'otcdocstheme',
 ]
 
 otcdocs_auto_name = False
@@ -30,6 +30,17 @@ otcdocs_repo_name = 'docs/web-application-firewall-dedicated'
 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 = '/web-application-firewall-dedicated/umn/'
+otcdocs_doc_title = 'User Guide'
+otcdocs_doc_type = 'umn'
+otcdocs_service_category = 'security-services'
+otcdocs_service_title = 'Dedicated Web Application Firewall'
+otcdocs_service_type = 'wafd'
+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.