internet/kubevirt.core
3
0
Fork 0
mirror of https://github.com/kubevirt/kubevirt.core.git synced 2026-05-07 05:42:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

first commit

Browse Source 
Signed-off-by: Felix Matouschek <fmatouschek@redhat.com>
This commit is contained in:
Felix Matouschek
2023-07-14 10:30:20 +02:00
commit 216df38df9
45 changed files with 3390 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/CHANGELOG.rst Symbolic link
View File

@@ -0,0 +1 @@
../CHANGELOG.rst

1
docs/CONTRIBUTING.md Symbolic link
View File

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

1
docs/README.md Symbolic link
View File

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

21
docs/_gh_include/footer.inc Normal file
View File

@@ -0,0 +1,21 @@
</ul>
</div>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2023 Red Hat, Inc.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
</body>
</html>

43
docs/_gh_include/header.inc Normal file
View File

@@ -0,0 +1,43 @@
<!doctype html>
<html>
<head>
<title>Kubevirt Ansible Collection documentation index</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" href="https://ansible-middleware.github.io/amq/main/_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="https://ansible-middleware.github.io/amq/main/_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="https://ansible-middleware.github.io/amq/main/_static/ansible-basic-sphinx-ext.css" type="text/css" />
<script data-url_root="./" id="documentation_options" src="https://ansible-middleware.github.io/amq/main/_static/documentation_options.js"></script>
<script src="https://ansible-middleware.github.io/amq/main/_static/jquery.js"></script>
<script src="https://ansible-middleware.github.io/amq/main/_static/underscore.js"></script>
<script src="https://ansible-middleware.github.io/amq/main/_static/doctools.js"></script>
<script src="https://ansible-middleware.github.io/amq/main/_static/js/theme.js"></script>
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="#" class="icon icon-home"> Kubevirt Ansible Collection</a>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="#" class="icon icon-home"></a> &raquo;</li>
<li>Welcome to Kubevirt Collection documentation</li>
<li class="wy-breadcrumbs-aside"></li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="welcome-to-amq-collection-documentation">
<h1>Welcome to Kubevirt Collection documentation<a class="headerlink" href="#welcome-to-amq-collection-documentation" title="Permalink to this headline"></a></h1>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Pick collection version:</span></p>
<ul>

170
docs/conf.py Normal file
View File

@@ -0,0 +1,170 @@
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# 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 datetime
import os
import sys
sys.path.insert(0, os.path.abspath('../plugins/module_utils/'))
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Kubevirt Ansible Collection'
copyright = '{y} Red Hat, Inc.'.format(y=datetime.date.today().year)
author = 'Red Hat, Inc.'
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = ''
# -- 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.intersphinx',
'ansible_basic_sphinx_ext',
]
# 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', '.md']
# The master toctree document.
master_doc = 'index'
# 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 = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.tmp']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
highlight_language = 'YAML+Jinja'
# -- Options for HTML output -------------------------------------------------
html_theme_path = ['_themes']
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
# html_theme = 'alabaster'
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 = {}
# 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 = []
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'KubevirtCollectionDoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'KubevirtCollection.tex', 'Red Hat Kubevirt Ansible Collection Documentation',
'Red Hat, Inc.', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'KubevirtCollection', 'Red Hat Kubevirt Ansible Collection Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'KubevirtCollection', 'Red Hat Kubevirt Ansible Collection Documentation',
author, 'KubevirtCollection', 'One line description of project.',
'Miscellaneous'),
]
# -- Extension configuration -------------------------------------------------
# -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'python': ('https://docs.python.org/2', None), 'ansible': ('https://docs.ansible.com/ansible/latest/', None)}

13
docs/developing.md Normal file
View File

@@ -0,0 +1,13 @@
## Contributor's Guidelines
- All YAML files named with `.yml` extension
- Use spaces around jinja variables. `{{ var }}` over `{{var}}`
- Variables that are internal to the role should be lowercase and start with the role name
- Keep roles self contained - Roles should avoid including tasks from other roles when possible
- Plays should do nothing more than include a list of roles except where `pre_tasks` and `post_tasks` are required when possible
- Separators - Use valid name, ie. underscores (e.g. `my_role` `my_playbook`) not dashes (`my-role`)
- Paths - When defining paths, do not include trailing slashes (e.g. `my_path: /foo` not `my_path: /foo/`). When concatenating paths, follow the same convention (e.g. `{{ my_path }}/bar` not `{{ my_path }}bar`)
- Indentation - Use 2 spaces for each indent
- `vars/` vs `defaults/` - internal or interpolated variables that don't need to change or be overridden by user go in `vars/`, those that a user would likely override, go under `defaults/` directory
- All arguments have a specification in `meta/argument_specs.yml`
- All playbooks/roles should be focused on compatibility with Ansible Automation Platform

45
docs/docsite/links.yml Normal file
View File

@@ -0,0 +1,45 @@
---
# This will make sure that plugin and module documentation gets Edit on GitHub links
# that allow users to directly create a PR for this plugin or module in GitHub's UI.
# Remove this section if the collection repository is not on GitHub, or if you do not want this
# functionality for your collection.
edit_on_github:
repository: ansible-collections/community.REPO_NAME
branch: main
# If your collection root (the directory containing galaxy.yml) does not coincide with your
# repository's root, you have to specify the path to the collection root here. For example,
# if the collection root is in a subdirectory ansible_collections/community/REPO_NAME
# in your repository, you have to set path_prefix to 'ansible_collections/community/REPO_NAME'.
path_prefix: ''
# Here you can add arbitrary extra links. Please keep the number of links down to a
# minimum! Also please keep the description short, since this will be the text put on
# a button.
#
# Also note that some links are automatically added from information in galaxy.yml.
# The following are automatically added:
# 1. A link to the issue tracker (if `issues` is specified);
# 2. A link to the homepage (if `homepage` is specified and does not equal the
# `documentation` or `repository` link);
# 3. A link to the collection's repository (if `repository` is specified).
extra_links:
- description: Report an issue
url: https://github.com/ansible-collections/community.REPO_NAME/issues/new/choose
# Specify communication channels for your collection. We suggest to not specify more
# than one place for communication per communication tool to avoid confusion.
communication:
matrix_rooms:
- topic: General usage and support questions
room: '#users:ansible.im'
irc_channels:
- topic: General usage and support questions
network: Libera
channel: '#ansible'
mailing_lists:
- topic: Ansible Project List
url: https://groups.google.com/g/ansible-project
# You can also add a `subscribe` field with an URI that allows to subscribe
# to the mailing list. For lists on https://groups.google.com/ a subscribe link is
# automatically generated.

26
docs/index.rst Normal file
View File

@@ -0,0 +1,26 @@
.. Red Hat kubernetes kubevirt Ansible Collection documentation main file
Welcome to Kubevirt Collection documentation
=======================================
.. toctree::
:maxdepth: 2
:caption: User documentation
README
plugins/index
roles/index
.. toctree::
:maxdepth: 2
:caption: Developer documentation
testing
developing
releasing
.. toctree::
:maxdepth: 2
:caption: General
Changelog <CHANGELOG>

61
docs/releasing.md Normal file
View File

@@ -0,0 +1,61 @@
# Collection Versioning Strategy
Each supported collection maintained by Ansible follows Semantic Versioning 2.0.0 (https://semver.org/), for example:
Given a version number MAJOR.MINOR.PATCH, the following is incremented:
MAJOR version: when making incompatible API changes (see Feature Release scenarios below for examples)
MINOR version: when adding features or functionality in a backwards compatible manner, or updating testing matrix and/or metadata (deprecation)
PATCH version: when adding backwards compatible bug fixes or security fixes (strict).
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
The first version of a generally available supported collection on Ansible Automation Hub shall be version 1.0.0. NOTE: By default, all newly created collections may begin with a smaller default version of 0.1.0, and therefore a version of 1.0.0 should be explicitly stated by the collection maintainer.
## New content is added to an existing collection
Assuming the current release is 1.0.0, and a new module is ready to be added to the collection, the minor version would be incremented to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.
## New feature to existing plugin or role within a collection (backwards compatible)
Assuming the current release is 1.0.0, and new features for an existing module are ready for release . We would increment the MINOR version to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.
## Bug fix or security fix to existing content within a collection
Assuming the current release is 1.0.0 and a bug is fixed prior to the next minor release, the PATCH version would be incremented to 1.0.1. The patch indicates only a bug was fixed within a current version. The PATCH release does not contain new content, nor was functionality removed. Bug fixes may be included in a MINOR or MAJOR feature release if the timing allows, eliminating the need for a PATCH dedicated to the fix.
## Breaking change to any content within a collection
Assuming the current release is 1.0.0, and a breaking change (API or module) is introduced for a user or developer. The MAJOR version would be incremented to 2.0.0.
Examples of breaking changes within a collection may include but are not limited to:
- Argspec changes for a module that require either inventory structure or playbook changes.
- A change in the shape of either the inbound or returned payload of a filter plugin.
- Changes to a connection plugin that require additional inventory parameters or ansible.cfg entries.
- New functionality added to a module that changes the outcome of that module as released in previous versions.
- The removal of plugins from a collection.
## Content removed from a collection
Deleting a module or API is a breaking change. Please see the 'Breaking change' section for how to version this.
## A typographical error was fixed in the documentation for a collection
A correction to the README would be considered a bug fix and the PATCH incremented. See 'Bug fix' above.
## Documentation added/removed/modified within a collection
Only the PATCH version should be increased for a release that contains changes limited to revised documentation.
## Release automation
New releases are triggered by annotated git tags named after semantic versioning. The automation publishes the built artifacts to ansible-galaxy and github releases page.

7
docs/requirements.txt Normal file
View File

@@ -0,0 +1,7 @@
antsibull>=0.17.0
antsibull-docs
antsibull-changelog
ansible-core>=2.14.1
sphinx-rtd-theme
git+https://github.com/felixfontein/ansible-basic-sphinx-ext
myst-parser

4
docs/roles.rst.template Normal file
View File

@@ -0,0 +1,4 @@
Role Index
==========
.. toctree::

35
docs/testing.md Normal file
View File

@@ -0,0 +1,35 @@
# Testing
## Continuous integration
The collection is tested with a [molecule](https://github.com/ansible-community/molecule) setup covering the included roles and verifying correct installation and idempotency.
In order to run the molecule tests locally with python 3.9 available, after cloning the repository:
```
pip install yamllint 'molecule[docker]~=3.5.2' ansible-core flake8 ansible-lint voluptuous
molecule test --all
```
## Test playbooks
Sample playbooks are provided in the `playbooks/` directory; to run the playbooks locally (requires a rhel system with python 3.9+, ansible, and systemd) the steps are as follows:
```
# setup environment
pip install ansible-core
# clone the repository
git clone https://github.com/ansible-middleware/amq
cd amq
# install collection dependencies
ansible-galaxy collection install -r requirements.yml
# install collection python deps
pip install -r requirements.txt
# create inventory for localhost
cat << EOF > inventory
[amq]
localhost ansible_connection=local
EOF
# run the playbook
ansible-playbook -i inventory playbooks/activemq.yml
```