Fix auto doc generation

Change-Id: Id176d784c292e26f152f5a1a8468f5b6e55cc2f0
This commit is contained in:
Angus Salkeld 2016-03-21 13:51:13 +10:00
parent cacdf3fb28
commit 23dd5b601d
14 changed files with 109 additions and 253 deletions

1
doc/source/api/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
*.rst

View File

@ -1,6 +0,0 @@
--------------
Chronos client
--------------
.. automodule:: kolla_mesos.chronos
:members:

View File

@ -15,16 +15,21 @@
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
sys.path.insert(0, ROOT)
sys.path.insert(0, BASE_DIR)
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx',
'oslosphinx'
]
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'oslosphinx']
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
@ -33,6 +38,9 @@ extensions = [
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
@ -40,6 +48,10 @@ master_doc = 'index'
project = u'kolla-mesos'
copyright = u'2013, OpenStack Foundation'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['**/#*', '**~', '**/#*#']
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True
@ -50,6 +62,13 @@ add_module_names = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
primary_domain = 'py'
nitpicky = False
# -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
@ -73,3 +92,14 @@ latex_documents = [
# Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None}
# -- Options for manual page output -------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('man/kolla-mesos', 'kolla-mesos',
u'Shell to access kolla-mesos.',
[u'Kolla-Mesos Developers'], 1),
]

View File

@ -1,5 +0,0 @@
--------------
Deploy command
--------------
.. automodule:: kolla_mesos.cmd.deploy

View File

@ -46,9 +46,7 @@ Code documentation
.. toctree::
:maxdepth: 1
deploy
chronos
marathon
api/autoindex
Indices and tables
==================

View File

@ -5,6 +5,4 @@ Man pages for utilities
.. toctree::
:maxdepth: 2
kolla-mesos-deploy
kolla-mesos-config
kolla-mesos-cleanup
kolla-mesos

View File

@ -1,17 +0,0 @@
===================
kolla-mesos-cleanup
===================
.. program:: kolla-mesos-cleanup
SYNOPSIS
========
DESCRIPTION
===========
INVENTORY
=========
OPTIONS
=======

View File

@ -1,61 +0,0 @@
==================
kolla-mesos-config
==================
.. program:: kolla-mesos-config
SYNOPSIS
========
DESCRIPTION
===========
INVENTORY
=========
OPTIONS
=======
.. cmdoption:: --config-dir DIR
Path to a config directory to pull .conf files from. This file set is sorted,
so as to provide a predictable parse order if individual options are
over-ridden. The set is parsed after the file(s) specified via previous
--config-file, arguments hence over-ridden options in the directory take precedence.
.. cmdoption:: --config-file PATH
Path to a config file to use. Multiple config files can be specified, with
values in later files taking precedence. The default files used are: None.
.. cmdoption:: --noshow
The inverse of --show
.. cmdoption:: --path PATH
.. cmdoption:: --show
.. cmdoption:: --version
show program's version number and exit
.. cmdoption:: --zookeeper-host ZOOKEEPER_HOST
ZooKeeper connection URL (host:port)
.. cmdoption:: --network-ipv6
Use IPv6 protocol
.. cmdoption:: --network-noipv6
The inverse of --ipv6
.. cmdoption:: --network-private-interface NETWORK_PRIVATE_INTERFACE
NIC connected to the private network
.. cmdoption:: --network-public-interface NETWORK_PUBLIC_INTERFACE
NIC connected to the public network

View File

@ -1,121 +0,0 @@
==================
kolla-mesos-deploy
==================
.. program:: kolla-mesos-deploy
SYNOPSIS
========
``kolla-mesos-deploy [options]``
DESCRIPTION
===========
kolla-mesos-deploy runs kolla containers on Mesos (Marathon+Chronos) cluster.
INVENTORY
=========
kolla-mesos-deploy saves configuration files for each OpenStack service on
ZooKeeper and uses HTTP requests to call Marathon and Chronos API.
OPTIONS
=======
.. cmdoption:: --config-dir DIR
Path to a config directory to pull .conf files from. This file set is
sorted, so as to provide a predictable parse order if individual options are
over-ridden. The set is parsed after the file(s) specified via previous
--config-file, arguments hence over-ridden options in the directory take
precedence.
.. cmdoption:: --config-file PATH
Path to a config file to use. Multiple config files can be specified, with
values in later files taking precedence. The default files used are: None.
.. cmdoption:: --force
.. cmdoption:: --noforce
The inverse of --force
.. cmdoption:: --noupdate
The inverse of --update
.. cmdoption:: --update
.. cmdoption:: --version
show program's version number and exit
--profiles-aux PROFILES_AUX
--profiles-default PROFILES_DEFAULT
--profiles-gate PROFILES_GATE
--profiles-infra PROFILES_INFRA
--profiles-main PROFILES_MAIN
.. cmdoption:: --kolla-base KOLLA_BASE
The base distro which was used to build images
.. cmdoption:: --kolla-base-tag KOLLA_BASE_TAG
The base distro image tag
.. cmdoption:: --kolla-install-type KOLLA_INSTALL_TYPE
The method of the OpenStack install
.. cmdoption:: --kolla-namespace KOLLA_NAMESPACE
The Docker namespace name
.. cmdoption:: --kolla-profile KOLLA_PROFILE
Build profile which was used to build images
.. cmdoption:: --kolla-tag KOLLA_TAG
The Docker tag
.. cmdoption:: --marathon-host MARATHON_HOST
Marathon connection URL (http://host:port)
.. cmdoption:: --marathon-timeout MARATHON_TIMEOUT
Timeout for the request to the Marathon API
.. cmdoption:: --zookeeper-host ZOOKEEPER_HOST
ZooKeeper connection URL (host:port)
.. cmdoption:: --chronos-host CHRONOS_HOST
Chronos connection URL (http://host:port)
.. cmdoption:: --chronos-timeout CHRONOS_TIMEOUT
Timeout for the request to the Chronos API
.. cmdoption:: --network-ipv6
Use IPv6 protocol
.. cmdoption:: --network-noipv6
The inverse of --ipv6
.. cmdoption:: --network-private-interface NETWORK_PRIVATE_INTERFACE
NIC connected to the private network
.. cmdoption:: --network-public-interface NETWORK_PUBLIC_INTERFACE
NIC connected to the public network
FILES
=====
* /etc/kolla-mesos/kolla-mesos.conf

View File

@ -0,0 +1,25 @@
===========
kolla-mesos
===========
.. program:: kolla-mesos
SYNOPSIS
========
``kolla-mesos [options]``
DESCRIPTION
===========
kolla-mesos runs kolla containers on Mesos (Marathon+Chronos) cluster.
INVENTORY
=========
OPTIONS
=======
FILES
=====
* /etc/kolla-mesos/kolla-mesos.conf

View File

@ -1,6 +0,0 @@
---------------
Marathon client
---------------
.. automodule:: kolla_mesos.marathon
:members:

View File

@ -123,9 +123,8 @@ the registry::
sudo kolla-build --profile mesos
``kolla-build`` accepts arguments as documented in :doc:`image-building`. It
builds Docker images and pushes them to the local registry if the *push*
option is enabled (in Vagrant this is the default behaviour).
``kolla-build`` builds Docker images and pushes them to the local registry if
the *push* option is enabled (in Vagrant this is the default behaviour).
Setting up Mesos cluster

View File

@ -71,22 +71,25 @@ def _get_config_tasks(config_path, tasks):
def get_tasks(config_path):
"""Get list of tasks
"""Get list of tasks.
Reads through all the kolla mesos services config files located in
config_path and parses the requirements and resister options.
Returns a dictionary of all the values registered by tasks
{
taskpath1: {
'requires': [require1, require2...]
'register': register_path
}
}
:returns: a dictionary of all the values registered by tasks
taskpath examples -
'keystone/keystone/db_sync',
'keystone/keystone_ansible_tasks/create_database',
Below is an example of what can be returned::
{
taskpath1: {
'requires': [require1, require2...]
'register': register_path
}
}
taskpath examples -
'keystone/keystone/db_sync',
'keystone/keystone_ansible_tasks/create_database',
"""
tasks = {}
@ -111,22 +114,25 @@ def get_service_tasks(service_name, service_dir):
def get_status(tasks):
"""Get status from zookeeper
"""Get status from zookeeper.
Returns the status for each task
{
task1: {
'register': (register_path, reg_status)
'requirements': {
reqt1_path: req_status
reqt2_path: req_status
...
:returns: the status for each task
Below is an example of what can be returned::
{
task1: {
'register': (register_path, reg_status)
'requirements': {
reqt1_path: reqt_status
reqt2_path: reqt_status
...
}
}
}
Where:
reg_status = 'done', 'running', 'waiting'
req_status = '', 'done'
Where:
reg_status = 'done', 'running', 'waiting'
reqt_status = '', 'done'
"""
status = {}
with zk_utils.connection() as zk:

View File

@ -62,6 +62,21 @@ kolla_mesos.cli =
oslo.config.opts =
kolla_mesos = kolla_mesos.opts:list_opts
[global]
setup-hooks =
pbr.hooks.setup_hook
[pbr]
autodoc_index_modules = true
autodoc_exclude_modules =
*.tests.*
kolla_mesos.cmd.*
kolla_mesos.config.*
kolla_mesos.opts
kolla_mesos.cli.*
kolla_mesos.common.*
kolla_mesos.container_scripts.*
[build_sphinx]
source-dir = doc/source
build-dir = doc/build