Create tox environment to build pdf documentation

This patch enables building .pdf documentation using new 'pdf-docs'
tox environment. The newly created tox environment creates latex
source codes using sphinx-build and then builds the pdf
documentation using make.

Also, convert README.md to README.rst for more seamless integration
of the README file in the pdf and html documentation.

Story: 2006070
Task: 35457

Change-Id: I5c022478c9be0067c125efb4032c16cf0978330f
This commit is contained in:
Lukas Piwowarski 2020-09-10 17:38:21 +02:00
parent 6f48063468
commit bc1beebf38
6 changed files with 115 additions and 88 deletions

View File

@ -1,86 +0,0 @@
Team and repository tags
========================
[![Team and repository tags](https://governance.openstack.org/tc/badges/devstack-plugin-ceph.svg)](https://governance.openstack.org/tc/reference/tags/index.html)
Devstack Ceph Plugin
====================
# Overview
Devstack plugin to configure Ceph as the storage backend for openstack services
As part of ```stack.sh```:
* Installs Ceph (client and server) packages
* Creates a Ceph cluster for use with openstack services
* Configures Ceph as the storage backend for Cinder, Cinder Backup, Nova,
Manila (not by default), and Glance services
* (Optionally) Sets up & configures Rados gateway (aka rgw or radosgw) as a Swift endpoint with Keystone integration
* Set ```ENABLE_CEPH_RGW=True``` in your ```localrc```
* Supports Ceph cluster running local or remote to openstack services
As part of ```unstack.sh``` | ```clean.sh```:
* Tears down the Ceph cluster and its related services
This plugin also gets used to configure Ceph as the storage backend for the upstream Ceph CI job named ```gate-tempest-dsvm-full-devstack-plugin-ceph```
# Usage
* To get started quickly, just enable the plugin in your ```local.conf```:
```enable_plugin devstack-plugin-ceph https://opendev.org/openstack/devstack-plugin-ceph```
Run ```stack.sh``` in your devstack tree and boom! You're good to go.
* Ceph is setup as the default storage backend for Cinder, Cinder Backup,
Glance and Nova services. You have the ability to control each of the
enabled services with the following configuration in your ```local.conf```:
```
ENABLE_CEPH_CINDER=True # ceph backend for cinder
ENABLE_CEPH_GLANCE=True # store images in ceph
ENABLE_CEPH_C_BAK=True # backup volumes to ceph
ENABLE_CEPH_NOVA=True # allow nova to use ceph resources
```
Change any of the above lines to ```False``` to disable that feature
specifically.
* Ceph can be enabled as the storage backend for Manila with the following
setting in your ```local.conf```:
```
ENABLE_CEPH_MANILA=True
```
CephFS Native driver that supports native Ceph protocol is used by default.
To use CephFS NFS-Ganesha driver that supports NFS protocol add the setting:
```
MANILA_CEPH_DRIVER=cephfsnfs
```
Make sure that the manila plugin is enabled before devstack-plugin-ceph in
the ```local.conf``` file.
* Then run ```stack.sh``` and wait for the _magic_ to happen :)
# Known Issues / Limitations
* Rados Gateway with Keystone for Swift - works on Ubuntu only
* Tempest test failures when using RGW as swift endpoint
* Tempest fails due to verify-tempest-config erroring out, when using RGW as swift endpoint
* Patch sent @ https://review.openstack.org/#/c/264179/
* Manila with CephFS - for Ubuntu, support only for Trusty Tahr (14.04 LTS) and beyond
# TODOs
* Fix Rados Gateway with Keystone for Swift on Fedora
# Bugs
* https://bugs.launchpad.net/devstack-plugin-ceph

97
README.rst Normal file
View File

@ -0,0 +1,97 @@
Devstack Ceph Plugin
====================
.. image:: https://governance.openstack.org/tc/badges/devstack-plugin-ceph.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
Overview
--------
Devstack plugin to configure Ceph as the storage backend for openstack
services
As part of ``stack.sh``:
- Installs Ceph (client and server) packages
- Creates a Ceph cluster for use with openstack services
- Configures Ceph as the storage backend for Cinder, Cinder Backup,
Nova, Manila (not by default), and Glance services
- (Optionally) Sets up & configures Rados gateway (aka rgw or radosgw)
as a Swift endpoint with Keystone integration
- Set ``ENABLE_CEPH_RGW=True`` in your ``localrc``
- Supports Ceph cluster running local or remote to openstack services
As part of ``unstack.sh`` \| ``clean.sh``:
- Tears down the Ceph cluster and its related services
This plugin also gets used to configure Ceph as the storage backend for
the upstream Ceph CI job named
``gate-tempest-dsvm-full-devstack-plugin-ceph``
Usage
-----
- To get started quickly, just enable the plugin in your
``local.conf``:
``enable_plugin devstack-plugin-ceph https://opendev.org/openstack/devstack-plugin-ceph``
Run ``stack.sh`` in your devstack tree and boom! You're good to go.
- Ceph is setup as the default storage backend for Cinder, Cinder
Backup, Glance and Nova services. You have the ability to control
each of the enabled services with the following configuration in your
``local.conf``:
::
ENABLE_CEPH_CINDER=True # ceph backend for cinder
ENABLE_CEPH_GLANCE=True # store images in ceph
ENABLE_CEPH_C_BAK=True # backup volumes to ceph
ENABLE_CEPH_NOVA=True # allow nova to use ceph resources
Change any of the above lines to ``False`` to disable that feature
specifically.
- Ceph can be enabled as the storage backend for Manila with the
following setting in your ``local.conf``:
::
ENABLE_CEPH_MANILA=True
CephFS Native driver that supports native Ceph protocol is used by
default. To use CephFS NFS-Ganesha driver that supports NFS protocol add
the setting:
::
MANILA_CEPH_DRIVER=cephfsnfs
Make sure that the manila plugin is enabled before devstack-plugin-ceph
in the ``local.conf`` file.
- Then run ``stack.sh`` and wait for the *magic* to happen :)
Known Issues / Limitations
--------------------------
- Rados Gateway with Keystone for Swift - works on Ubuntu only
- Tempest test failures when using RGW as swift endpoint
- Tempest fails due to verify-tempest-config erroring out, when using
RGW as swift endpoint
- Patch sent @ https://review.openstack.org/#/c/264179/
- Manila with CephFS - for Ubuntu, support only for Trusty Tahr (14.04
LTS) and beyond
TODOs
-----
- Fix Rados Gateway with Keystone for Swift on Fedora
Bugs
----
- https://bugs.launchpad.net/devstack-plugin-ceph

View File

@ -3,3 +3,4 @@
# process, which may cause wedges in the gate later.
openstackdocstheme>=2.2.1 # Apache-2.0
sphinx>=2.0.0,!=2.1.0 # BSD
sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD

View File

@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.autodoc',
'sphinxcontrib.rsvgconverter',
#'sphinx.ext.intersphinx',
'openstackdocstheme'
]
@ -32,6 +33,7 @@ openstackdocs_bug_project = 'devstack-plugin-ceph'
openstackdocs_bug_tag = ''
openstackdocs_auto_version = False
openstackdocs_auto_name = False
openstackdocs_pdf_link = True
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
@ -72,10 +74,15 @@ htmlhelp_basename = '%sdoc' % project
# [howto/manual]).
latex_documents = [
('index',
'%s.tex' % project,
'doc-devstack-plugin-ceph.tex',
u'%s Documentation' % project,
u'OpenStack Foundation', 'manual'),
]
# Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None}
latex_use_xindy = False
latex_elements = {
'extraclassoptions': 'openany,oneside',
}

View File

@ -1 +1 @@
.. include:: ../../README.md
.. include:: ../../README.rst

View File

@ -32,3 +32,11 @@ commands =
rm -rf doc/build
sphinx-build -W -b html doc/source doc/build/html
whitelist_externals = rm
[testenv:pdf-docs]
deps = {[testenv:docs]deps}
whitelist_externals =
make
commands =
sphinx-build -W -b latex doc/source doc/build/pdf
make -C doc/build/pdf