From 220d807ec9e88787ae5558c9a07c2eed5437562f 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. --- .readthedocs.yaml | 29 +++++++++++ CONTRIBUTING.md | 1 + Makefile | 12 +++++ docs/Makefile_orig | 20 ++++++++ docs/doc-requirements.txt | 8 ++++ docs/source/Makefile | 96 +++++++++++++++++++++++++++++++++++++ docs/source/conf.py | 96 +++++++++++++++++++++++++++++++++++++ docs/source/contributing.md | 1 + docs/source/index.rst | 21 ++++++++ docs/source/readme.md | 1 + 10 files changed, 285 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 CONTRIBUTING.md create mode 100644 docs/Makefile_orig create mode 100644 docs/doc-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/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..82cd1074 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,29 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/source/conf.py + +# If using Sphinx, optionally build your docs in additional formats such as PDF +# formats: +# - pdf + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/doc-requirements.txt \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b85dda86 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +# Contribute to the test-operator \ No newline at end of file diff --git a/Makefile b/Makefile index 3981328c..fa327e5b 100644 --- a/Makefile +++ b/Makefile @@ -316,3 +316,15 @@ 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/... + +VIRTENV_FOLDER_NAME = virtdocs +##@ Generate documentation +.PHONY: docs +docs: ## Create documentation under docs/build/html + cd docs && \ + python -m venv $(VIRTENV_FOLDER_NAME) && \ + . virtdocs/bin/activate && \ + pip install -r doc-requirements.txt && \ + cd source && \ + make html && \ + rm -rf $(VIRTENV_FOLDER_NAME) diff --git a/docs/Makefile_orig b/docs/Makefile_orig new file mode 100644 index 00000000..47d1eb36 --- /dev/null +++ b/docs/Makefile_orig @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = -W +SPHINXBUILD = sphinx-build +SPHINXPROJ = ci-framework +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt new file mode 100644 index 00000000..180e56b7 --- /dev/null +++ b/docs/doc-requirements.txt @@ -0,0 +1,8 @@ +pbr +sphinx>=1.5.1 +sphinx-autobuild +sphinx_rtd_theme +Pygments>=2.2.0 +reno>=2.5.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..5d89c177 --- /dev/null +++ b/docs/source/conf.py @@ -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'test-operator' +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' \ No newline at end of file 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..4a4800e9 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,21 @@ +.. 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 + + +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