From 06a9aa17036ed3d1c957df505bf389c34a0b31d4 Mon Sep 17 00:00:00 2001 From: Martin Kopec Date: Thu, 21 Sep 2023 15:19:46 +0200 Subject: [PATCH] Init documentation Prepare the documentation structure and configs required to build a documentation. --- .github/workflows/documentation.yaml | 57 ++++++++++++++++ .gitignore | 3 + CONTRIBUTING.md | 1 + Makefile | 5 ++ README.md | 9 ++- docs/build-docs.sh | 18 +++++ docs/doc8.ini | 3 + docs/requirements.txt | 7 ++ docs/source/Makefile | 96 +++++++++++++++++++++++++++ docs/source/conf.py | 98 ++++++++++++++++++++++++++++ docs/source/contributing.md | 1 + docs/source/index.rst | 27 ++++++++ docs/source/readme.md | 1 + 13 files changed, 321 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/documentation.yaml create mode 100644 CONTRIBUTING.md create mode 100755 docs/build-docs.sh create mode 100644 docs/doc8.ini create mode 100644 docs/requirements.txt create mode 100644 docs/source/Makefile create mode 100644 docs/source/conf.py create mode 120000 docs/source/contributing.md create mode 100644 docs/source/index.rst create mode 120000 docs/source/readme.md diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml new file mode 100644 index 00000000..9728b0ce --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index 01f05dd7..05c65058 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,6 @@ CI_TOOLS_REPO .vscode/ go.work go.work.sum + +# doc +docs/build/* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..a5a1405a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +# Contribute to the test-operator diff --git a/Makefile b/Makefile index 3981328c..36f07003 100644 --- a/Makefile +++ b/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/operator-lint@v0.3.0 go vet -vettool=$(LOCALBIN)/operator-lint ./... ./api/... + +##@ Generate documentation +.PHONY: docs +docs: ## Create documentation under docs/build/html + docs/build-docs.sh diff --git a/README.md b/README.md index c5ef1f0a..397340b5 100644 --- a/README.md +++ b/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=/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. - diff --git a/docs/build-docs.sh b/docs/build-docs.sh new file mode 100755 index 00000000..682de46f --- /dev/null +++ b/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} diff --git a/docs/doc8.ini b/docs/doc8.ini new file mode 100644 index 00000000..06f32c0a --- /dev/null +++ b/docs/doc8.ini @@ -0,0 +1,3 @@ +[doc8] +extensions = .rst +ignore = D001 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..ee3ed71d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +ansible-core>=2.14.6 +sphinx>=6.2.1 # BSD +sphinx-autobuild>=2021.3.1 +sphinx_rtd_theme>=1.2.2 +doc8>=0.8.1 # Apache-2.0 +sphinxemoji +myst-parser diff --git a/docs/source/Makefile b/docs/source/Makefile new file mode 100644 index 00000000..3241a24d --- /dev/null +++ b/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' diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..dfa257dc --- /dev/null +++ b/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' diff --git a/docs/source/contributing.md b/docs/source/contributing.md new file mode 120000 index 00000000..f939e75f --- /dev/null +++ b/docs/source/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..b2eccdba --- /dev/null +++ b/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` diff --git a/docs/source/readme.md b/docs/source/readme.md new file mode 120000 index 00000000..fe840054 --- /dev/null +++ b/docs/source/readme.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file