Browse Source

Changes following becoming an official project

* Updates the documentation to use openstackdocstheme
* Try to make sphinx config more similar to other openstack projects
* Add publishing jobs for docs & release notes
* Update links to source and docs
* Add a version module

Change-Id: I5180e008382e294aa9808a4775e998776f21362a
changes/85/619585/3
Mark Goddard 3 years ago
parent
commit
49fb893b83
  1. 11
      README.rst
  2. 1
      doc/requirements.txt
  3. 8
      doc/source/architecture.rst
  4. 182
      doc/source/conf.py
  5. 4
      doc/source/configuration.rst
  6. 11
      doc/source/development.rst
  7. 0
      doc/source/images/tenks_ansible_structure.png
  8. 0
      doc/source/images/tenks_networking_structure.png
  9. 14
      doc/source/install.rst
  10. 9
      setup.cfg
  11. 0
      tenks/__init__.py
  12. 18
      tenks/version.py
  13. 5
      zuul.d/project.yaml

11
README.rst

@ -1,6 +1,9 @@
Tenks
=====
.. image:: https://governance.openstack.org/badges/metalsmith.svg
:target: https://governance.openstack.org/reference/tags/index.html
Tenks is a utility that manages virtual bare metal clusters for development and
testing purposes. It offers:
@ -19,8 +22,8 @@ testing purposes. It offers:
To get started with Tenks, see the documentation (linked below).
* Free software: Apache license
* Documentation: https://tenks.readthedocs.io/
* Source: https://github.com/stackhpc/tenks/
* Bugs: https://github.com/stackhpc/tenks/issues
* License: Apache License, Version 2.0
* Documentation: https://docs.openstack.org/tenks/
* Source: https://git.openstack.org/cgit/openstack/tenks/
* Bugs: https://storyboard.openstack.org/#!/project/openstack/tenks
* Known issues/limitations: refer to the documentation.

1
doc/requirements.txt

@ -1,2 +1,3 @@
sphinx>=1.8.0 # BSD
reno!=2.3.1,>=1.8.0 # Apache-2.0
openstackdocstheme>=1.18.1 # Apache-2.0

8
doc/source/architecture.rst

@ -16,8 +16,8 @@ red ellipses represent roles and yellow rhombi represent action plugins.
artifact can be produced.
https://drive.google.com/file/d/1MlmaTvJ2BPkhrOCLin4GPH265JDJqD1E/view?usp=sharing
.. image:: _static/tenks_ansible_structure.png
:target: _static/tenks_ansible_structure.png
.. image:: images/tenks_ansible_structure.png
:width: 100%
Networking
----------
@ -45,5 +45,5 @@ An example of the networking structure of Tenks is shown below. In this
example, one node was requested to be connected to physnet0 and physnet1, and
two nodes were requested to be connected just to physnet1.
.. image:: _static/tenks_networking_structure.png
:target: _static/tenks_networking_structure.png
.. image:: images/tenks_networking_structure.png
:width: 100%

182
doc/source/conf.py

@ -1,39 +1,18 @@
# -*- coding: utf-8 -*-
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# Configuration file for the Sphinx documentation builder.
# http://www.apache.org/licenses/LICENSE-2.0
#
# 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
# Unless required by applicable law or agreed to in writing, software
# 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.
# -- 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 os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = u'Tenks'
copyright = u'2018, Will Miller'
author = u'Will Miller'
# The short X.Y version
version = u''
# The full version, including alpha/beta/rc tags
release = u''
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@ -41,6 +20,13 @@ release = u''
extensions = [
]
try:
import openstackdocstheme
extensions.append('openstackdocstheme')
except ImportError:
openstackdocstheme = None
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -53,121 +39,51 @@ source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# General information about the project.
project = u'Tenks'
copyright = u'OpenStack Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# 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
# The short X.Y version.
from tenks import version as tenks_version
# The full version, including alpha/beta/rc tags.
release = tenks_version.version_info.release_string()
# The short X.Y version.
version = tenks_version.version_info.version_string()
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# 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 = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- 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 = 'alabaster'
# 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 = ['_static']
# -- Options for HTML output --------------------------------------------------
# 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 ---------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
if openstackdocstheme is not None:
html_theme = 'openstackdocs'
else:
html_theme = 'default'
# Output file base name for HTML help builder.
htmlhelp_basename = 'Tenksdoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
htmlhelp_basename = '%sdoc' % project
# 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, 'Tenks.tex', u'Tenks Documentation',
u'Will Miller', '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, 'tenks', u'Tenks Documentation',
[author], 1)
(
master_doc,
'%s.tex' % project,
u'%s Documentation' % project,
u'OpenStack Foundation',
'manual'
),
]
# -- 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, 'Tenks', u'Tenks Documentation',
author, 'Tenks', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']

4
doc/source/configuration.rst

@ -17,8 +17,8 @@ setup on the host where the ``ansible-playbook`` command is executed
must contain one or more system. Systems in its sub-groups will host a subset
of the nodes deployed by Tenks.
* The ``libvirt`` group is a sub-group of ``hypervisors``. Systems in this
group will act as hypervisors using the Libvirt provider.
* The ``libvirt`` group is a sub-group of ``hypervisors``. Systems in this
group will act as hypervisors using the Libvirt provider.
Variable Configuration
----------------------

11
doc/source/development.rst

@ -56,7 +56,10 @@ to be implemented in future.
Contribution
------------
Contribution to Tenks' development is welcomed. Currently, the correct workflow
is to raise an issue in the `GitHub repository
<https://github.com/stackhpc/tenks/>`_. Patches should be submitted for review
using a GitHub pull request.
Contribution to Tenks' development is welcomed. Tenks uses the `OpenStack
development processes
<https://docs.openstack.org/infra/manual/developers.html>`__. Code reviews
should be submitted to `Gerrit
<https://review.openstack.org/#/q/project:openstack/tenks>`__, and bugs and
RFEs submitted to `StoryBoard
<https://storyboard.openstack.org/#!/project/openstack/tenks>`__.

0
doc/source/_static/tenks_ansible_structure.png → doc/source/images/tenks_ansible_structure.png

Before

Width: 1262  |  Height: 518  |  Size: 93 KiB

After

Width: 1262  |  Height: 518  |  Size: 93 KiB

0
doc/source/_static/tenks_networking_structure.png → doc/source/images/tenks_networking_structure.png

Before

Width: 742  |  Height: 590  |  Size: 98 KiB

After

Width: 742  |  Height: 590  |  Size: 98 KiB

14
doc/source/install.rst

@ -15,13 +15,13 @@ It is assumed that...
* ...you already have an OpenStack cloud deployed, for which...
* ...the host from which Tenks is executed (*localhost*) has access to the
OpenStack APIs. These are used for Ironic node enrolment and Nova flavor
registration.
* ...the host from which Tenks is executed (*localhost*) has access to the
OpenStack APIs. These are used for Ironic node enrolment and Nova flavor
registration.
* ...the OpenStack *OS_\** authentication variables are present in
*localhost*'s environment. These can typically be sourced from your
*openrc* file.
* ...the OpenStack *OS_\** authentication variables are present in
*localhost*'s environment. These can typically be sourced from your
*openrc* file.
* ... a distinct network device (interface or bridge) is present for each
physical network that a hypervisor is connected to.
@ -53,7 +53,7 @@ Activate the virtualenv and update pip::
Obtain the Tenks source code and change into the directory. For example::
(tenks) $ git clone https://github.com/stackhpc/tenks.git
(tenks) $ git clone https://git.openstack.org/openstack/tenks.git
(tenks) $ cd tenks
Install Tenks and its requirements using the source code checkout::

9
setup.cfg

@ -3,17 +3,20 @@ name = tenks
summary = Deployment of virtual bare metal clusters with Tenks
description-file =
README.rst
author = Will Miller
author-email = willm@stackhpc.com
home-page = https://stackhpc.com
author = OpenStack
author-email = openstack-dev@lists.openstack.org
home-page = https://docs.openstack.org/tenks/latest/
classifier =
Environment :: OpenStack
Intended Audience :: Information Technology
Intended Audience :: System Administrators
License :: OSI Approved :: Apache Software License
Operating System :: POSIX :: Linux
Programming Language :: Python
Programming Language :: Python :: 2
Programming Language :: Python :: 2.7
Programming Language :: Python :: 3
Programming Language :: Python :: 3.5
[files]
packages =

0
tenks/__init__.py

18
tenks/version.py

@ -0,0 +1,18 @@
# Copyright 2011 OpenStack Foundation
# All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# 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.
import pbr.version
version_info = pbr.version.VersionInfo('tenks')

5
zuul.d/project.yaml

@ -1,20 +1,19 @@
---
- project:
templates:
- build-openstack-docs-pti
- publish-openstack-docs-pti
- release-notes-jobs-python3
- openstack-cover-jobs
- openstack-python35-jobs
- openstack-python-jobs
check:
jobs:
- build-openstack-releasenotes
- tenks-tox-ansible-lint
- tenks-deploy-teardown-centos
- tenks-deploy-teardown-ubuntu
gate:
queue: tenks
jobs:
- build-openstack-releasenotes
- tenks-tox-ansible-lint
- tenks-deploy-teardown-centos
- tenks-deploy-teardown-ubuntu
Loading…
Cancel
Save