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:
parent
6f48063468
commit
bc1beebf38
86
README.md
86
README.md
|
@ -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
|
|
|
@ -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
|
||||||
|
|
|
@ -3,3 +3,4 @@
|
||||||
# process, which may cause wedges in the gate later.
|
# process, which may cause wedges in the gate later.
|
||||||
openstackdocstheme>=2.2.1 # Apache-2.0
|
openstackdocstheme>=2.2.1 # Apache-2.0
|
||||||
sphinx>=2.0.0,!=2.1.0 # BSD
|
sphinx>=2.0.0,!=2.1.0 # BSD
|
||||||
|
sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
|
||||||
|
|
|
@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
|
||||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||||
extensions = [
|
extensions = [
|
||||||
'sphinx.ext.autodoc',
|
'sphinx.ext.autodoc',
|
||||||
|
'sphinxcontrib.rsvgconverter',
|
||||||
#'sphinx.ext.intersphinx',
|
#'sphinx.ext.intersphinx',
|
||||||
'openstackdocstheme'
|
'openstackdocstheme'
|
||||||
]
|
]
|
||||||
|
@ -32,6 +33,7 @@ openstackdocs_bug_project = 'devstack-plugin-ceph'
|
||||||
openstackdocs_bug_tag = ''
|
openstackdocs_bug_tag = ''
|
||||||
openstackdocs_auto_version = False
|
openstackdocs_auto_version = False
|
||||||
openstackdocs_auto_name = False
|
openstackdocs_auto_name = False
|
||||||
|
openstackdocs_pdf_link = True
|
||||||
|
|
||||||
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
||||||
# text edit cycles.
|
# text edit cycles.
|
||||||
|
@ -72,10 +74,15 @@ htmlhelp_basename = '%sdoc' % project
|
||||||
# [howto/manual]).
|
# [howto/manual]).
|
||||||
latex_documents = [
|
latex_documents = [
|
||||||
('index',
|
('index',
|
||||||
'%s.tex' % project,
|
'doc-devstack-plugin-ceph.tex',
|
||||||
u'%s Documentation' % project,
|
u'%s Documentation' % project,
|
||||||
u'OpenStack Foundation', 'manual'),
|
u'OpenStack Foundation', 'manual'),
|
||||||
]
|
]
|
||||||
|
|
||||||
# Example configuration for intersphinx: refer to the Python standard library.
|
# Example configuration for intersphinx: refer to the Python standard library.
|
||||||
#intersphinx_mapping = {'http://docs.python.org/': None}
|
#intersphinx_mapping = {'http://docs.python.org/': None}
|
||||||
|
|
||||||
|
latex_use_xindy = False
|
||||||
|
latex_elements = {
|
||||||
|
'extraclassoptions': 'openany,oneside',
|
||||||
|
}
|
||||||
|
|
|
@ -1 +1 @@
|
||||||
.. include:: ../../README.md
|
.. include:: ../../README.rst
|
||||||
|
|
8
tox.ini
8
tox.ini
|
@ -32,3 +32,11 @@ commands =
|
||||||
rm -rf doc/build
|
rm -rf doc/build
|
||||||
sphinx-build -W -b html doc/source doc/build/html
|
sphinx-build -W -b html doc/source doc/build/html
|
||||||
whitelist_externals = rm
|
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
|
||||||
|
|
Loading…
Reference in New Issue