Init documentation

Prepare the documentation structure and configs required to build
a documentation.

.github/workflows/documentation.yaml

@@ -0,0 +1,57 @@
+name: Build documentation and deploy it to GitHub Pages
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  pages: write
+  id-token: write
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+          cache-dependency-path: ./docs/requirements.txt
+      - name: Build documentation
+        run: |
+          docs/build-docs.sh
+      - name: Upload artifacts
+        if: ${{ github.ref == 'refs/heads/main' }}
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: docs/build/html/
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name != 'pull_request'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        if: ${{ github.ref == 'refs/heads/main' }}
+        uses: actions/deploy-pages@v1

.gitignore

@@ -34,3 +34,6 @@ CI_TOOLS_REPO
 .vscode/
 go.work
 go.work.sum
+
+# doc
+docs/build/*

CONTRIBUTING.md

@@ -0,0 +1 @@
+# Contribute to the test-operator

Makefile

@@ -316,3 +316,8 @@ gowork: ## Generate go.work file to support our multi module repository
 operator-lint: gowork ## Runs operator-lint
 	GOBIN=$(LOCALBIN) go install github.com/gibizer/[email protected]
 	go vet -vettool=$(LOCALBIN)/operator-lint ./... ./api/...
+
+##@ Generate documentation
+.PHONY: docs
+docs: ## Create documentation under docs/build/html
+	docs/build-docs.sh

README.md

@@ -16,11 +16,11 @@ kubectl apply -f config/samples/
 ```
 
 2. Build and push your image to the location specified by `IMG`:
-	
+
 ```sh
 make docker-build docker-push IMG=<some-registry>/test-operator:tag
 ```
-	
+
 3. Deploy the controller to the cluster with the image specified by `IMG`:
 
 ```sh
@@ -47,8 +47,8 @@ make undeploy
 ### How it works
 This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
 
-It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) 
-which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster 
+It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
+which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster
 
 ### Test It Out
 1. Install the CRDs into the cluster:
@@ -91,4 +91,3 @@ 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.
-

docs/build-docs.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+set -euxo pipefail
+
+TEMP_VENV_ENV="$(mktemp -d)"
+DOCS_DIR="./docs"
+
+python -m venv ${TEMP_VENV_ENV} && source ${TEMP_VENV_ENV}/bin/activate
+
+pip install -c ${UPPER_CONSTRAINTS_FILE:-https://releases.openstack.org/constraints/upper/master} -r ${DOCS_DIR}/requirements.txt
+
+# Run linter on docs, skipping antsibull-docs output as it isn't up to spec
+doc8 --config ${DOCS_DIR}/doc8.ini ${DOCS_DIR}/source
+
+sphinx-build -a -E -W -d ${DOCS_DIR}/build/doctrees --keep-going -b html ${DOCS_DIR}/source ${DOCS_DIR}/build/html -T
+
+deactivate
+rm -fr ${TEMP_VENV_ENV}

docs/doc8.ini

@@ -0,0 +1,3 @@
+[doc8]
+extensions = .rst
+ignore = D001

docs/requirements.txt

@@ -0,0 +1,7 @@
+ansible-core>=2.14.6
+sphinx>=7.0.0 # BSD
+sphinx-autobuild>=2021.3.1
+sphinx_rtd_theme>=1.2.2
+doc8>=0.8.1 # Apache-2.0
+sphinxemoji
+myst-parser

docs/source/Makefile

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+#
+# this documentation build configuration file can be
+# created using sphinx-quickstart
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+import os
+import re
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['myst_parser',
+              'sphinx.ext.autodoc',
+              'sphinx.ext.doctest',
+              'sphinx.ext.intersphinx',
+              'sphinx.ext.todo',
+              'sphinx.ext.viewcode',
+              'sphinxemoji.sphinxemoji',
+              'reno.sphinxext']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'ci-framework'
+copyright = u'2023, Red Hat'
+
+# Versions
+# Get the latest release. Subject to be tagged as following:
+# v1.0
+# v2.0
+# v2.1
+get_version_command = 'git tag --sort=committerdate -l v* | tail -1'
+release = re.sub('^v', '', os.popen(get_version_command).read().strip())
+version = release
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+
+# 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 = {}
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+# htmlhelp_basename = 'doc'

docs/source/conf.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+#
+# this documentation build configuration file can be
+# created using sphinx-quickstart
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+import os
+import re
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinxemoji.sphinxemoji",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# The master toctree document.
+master_doc = "index"
+
+# General information about the project.
+project = "test-operator"
+copyright = "2023, Red Hat"
+
+# Versions
+# Get the latest release. Subject to be tagged as following:
+# v1.0
+# v2.0
+# v2.1
+get_version_command = "git tag --sort=committerdate -l v* | tail -1"
+release = re.sub("^v", "", os.popen(get_version_command).read().strip())
+version = release
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+# html_theme = "sphinx_rtd_theme"
+# html_logo = "images/logo_cifmw_200.png"
+
+# 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 = {}
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+# htmlhelp_basename = 'doc'

docs/source/contributing.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

docs/source/index.rst

@@ -0,0 +1,27 @@
+..  documentation master file
+
+=============
+test-operator
+=============
+
+Welcome to the documentation for test-operator. This documentation is designed
+to help you get up and running with our project as quickly and smoothly as
+possible.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Overview
+
+   readme.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: For Contributors
+
+   contributing.md
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

docs/source/readme.md

@@ -0,0 +1 @@
+../../README.md