From eaed6500008a296162b310b55634d3d1c9526917 Mon Sep 17 00:00:00 2001 From: David TARDIVEL Date: Fri, 15 Jan 2016 12:30:17 +0100 Subject: [PATCH] Refactor Commands section Rename this section to 'Watcher Manual Pages' and add man RST files. Partial-Bug: #1535244 Change-Id: I1c890c8d053238aa568075d844f97b1e4289adcb --- doc/source/conf.py | 33 ++++++++-- doc/source/index.rst | 9 +-- doc/source/man/footer.rst | 4 ++ doc/source/man/general-options.rst | 66 +++++++++++++++++++ doc/source/man/watcher-api.rst | 39 +++++++++++ doc/source/man/watcher-applier.rst | 39 +++++++++++ .../{cmds => man}/watcher-db-manage.rst | 0 doc/source/man/watcher-decision-engine.rst | 39 +++++++++++ 8 files changed, 218 insertions(+), 11 deletions(-) create mode 100644 doc/source/man/footer.rst create mode 100644 doc/source/man/general-options.rst create mode 100644 doc/source/man/watcher-api.rst create mode 100644 doc/source/man/watcher-applier.rst rename doc/source/{cmds => man}/watcher-db-manage.rst (100%) create mode 100644 doc/source/man/watcher-decision-engine.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index acf2da8f7..f472764b7 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -11,19 +11,14 @@ # implied. # See the License for the specific language governing permissions and # limitations under the License. - -import os -import sys from watcher import version as watcher_version -sys.path.insert(0, os.path.abspath('../..')) # -- 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', 'sphinx.ext.viewcode', 'sphinxcontrib.httpdomain', 'sphinxcontrib.pecanwsme.rest', @@ -46,8 +41,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'watcher' -copyright = u'2015, OpenStack Foundation' +project = u'Watcher' +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 @@ -62,6 +57,14 @@ version = watcher_version.version_info.version_string() # A list of ignored prefixes for module index sorting. modindex_common_prefix = ['watcher.'] +exclude_patterns = [ + # The man directory includes some snippet files that are included + # in other documents during the build but that should not be + # included in the toctree themselves, so tell Sphinx to ignore + # them when scanning for input files. + 'man/footer.rst', + 'man/general_options.rst', +] # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True @@ -73,6 +76,22 @@ add_module_names = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# -- Options for man page output -------------------------------------------- + +# Grouping the document tree for man pages. +# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' + +man_pages = [ + ('man/watcher-api', 'watcher-api', u'Watcher API Server', + [u'OpenStack'], 1), + ('man/watcher-applier', 'watcher-applier', u'Watcher Applier', + [u'OpenStack'], 1), + ('man/watcher-db-manage', 'watcher-db-manage', + u'Watcher Db Management Utility', [u'OpenStack'], 1), + ('man/watcher-decision-engine', 'watcher-decision-engine', + u'Watcher Decision Engine', [u'OpenStack'], 1), +] + # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. Major themes that come with diff --git a/doc/source/index.rst b/doc/source/index.rst index b3ce4cb7b..ef53ef686 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -62,13 +62,14 @@ Overview deploy/user-guide deploy/installation -Commands --------- +Watcher Manual Pages +==================== .. toctree:: - :maxdepth: 1 + :glob: + :maxdepth: 1 - cmds/watcher-db-manage + man/* Indices and tables diff --git a/doc/source/man/footer.rst b/doc/source/man/footer.rst new file mode 100644 index 000000000..584b173a9 --- /dev/null +++ b/doc/source/man/footer.rst @@ -0,0 +1,4 @@ +BUGS +==== + +* Watcher bugs are tracked in Launchpad at `OpenStack Watcher `__ \ No newline at end of file diff --git a/doc/source/man/general-options.rst b/doc/source/man/general-options.rst new file mode 100644 index 000000000..7f9185679 --- /dev/null +++ b/doc/source/man/general-options.rst @@ -0,0 +1,66 @@ + **-h, --help** + Show the help message and exit + + **--version** + Print the version number and exit + + **-v, --verbose** + Print more verbose output + + **--noverbose** + Disable verbose output + + **-d, --debug** + Print debugging output (set logging level to DEBUG instead of + default WARNING level) + + **--nodebug** + Disable debugging output + + **--use-syslog** + Use syslog for logging + + **--nouse-syslog** + Disable the use of syslog for logging + + **--syslog-log-facility SYSLOG_LOG_FACILITY** + syslog facility to receive log lines + + **--config-dir DIR** + Path to a config directory to pull \*.conf files from. This + file set is sorted, 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. This means + that configuration from files in a specified config-dir will + always take precedence over configuration from files specified + by --config-file, regardless to argument order. + + **--config-file PATH** + Path to a config file to use. Multiple config files can be + specified by using this flag multiple times, for example, + --config-file --config-file . Values in latter + files take precedence. + + **--log-config-append PATH** **--log-config PATH** + The name of logging configuration file. It does not + disable existing loggers, but just appends specified + logging configuration to any other existing logging + options. Please see the Python logging module documentation + for details on logging configuration files. The log-config + name for this option is depcrecated. + + **--log-format FORMAT** + A logging.Formatter log message format string which may use any + of the available logging.LogRecord attributes. Default: None + + **--log-date-format DATE_FORMAT** + Format string for %(asctime)s in log records. Default: None + + **--log-file PATH, --logfile PATH** + (Optional) Name of log file to output to. If not set, logging + will go to stdout. + + **--log-dir LOG_DIR, --logdir LOG_DIR** + (Optional) The directory to keep log files in (will be prepended + to --log-file) \ No newline at end of file diff --git a/doc/source/man/watcher-api.rst b/doc/source/man/watcher-api.rst new file mode 100644 index 000000000..d2f7fa8eb --- /dev/null +++ b/doc/source/man/watcher-api.rst @@ -0,0 +1,39 @@ +=========== +watcher-api +=========== + +--------------------------- +Service for the Watcher API +--------------------------- + +:Author: openstack@lists.launchpad.net +:Date: +:Copyright: OpenStack Foundation +:Version: +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + +watcher-api [options] + +DESCRIPTION +=========== + +watcher-api is a server daemon that serves the Watcher API + +OPTIONS +======= + + **General options** + + .. include:: general-options.rst + +FILES +===== + + **/etc/watcher/watcher.conf** + Default configuration file for Watcher API + +.. include:: footer.rst diff --git a/doc/source/man/watcher-applier.rst b/doc/source/man/watcher-applier.rst new file mode 100644 index 000000000..7f22b7659 --- /dev/null +++ b/doc/source/man/watcher-applier.rst @@ -0,0 +1,39 @@ +=============== +watcher-applier +=============== + +------------------------------- +Service for the Watcher Applier +------------------------------- + +:Author: openstack@lists.launchpad.net +:Date: +:Copyright: OpenStack Foundation +:Version: +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + +watcher-applier [options] + +DESCRIPTION +=========== + +:ref:`Watcher Applier ` + +OPTIONS +======= + + **General options** + + .. include:: general-options.rst + +FILES +===== + + **/etc/watcher/watcher.conf** + Default configuration file for Watcher Applier + +.. include:: footer.rst diff --git a/doc/source/cmds/watcher-db-manage.rst b/doc/source/man/watcher-db-manage.rst similarity index 100% rename from doc/source/cmds/watcher-db-manage.rst rename to doc/source/man/watcher-db-manage.rst diff --git a/doc/source/man/watcher-decision-engine.rst b/doc/source/man/watcher-decision-engine.rst new file mode 100644 index 000000000..3e07c3b81 --- /dev/null +++ b/doc/source/man/watcher-decision-engine.rst @@ -0,0 +1,39 @@ +======================= +watcher-decision-engine +======================= + +--------------------------------------- +Service for the Watcher Decision Engine +--------------------------------------- + +:Author: openstack@lists.launchpad.net +:Date: +:Copyright: OpenStack Foundation +:Version: +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + +watcher-decision-engine [options] + +DESCRIPTION +=========== + +:ref:`Watcher Decision Engine ` + +OPTIONS +======= + + **General options** + + .. include:: general-options.rst + +FILES +===== + + **/etc/watcher/watcher.conf** + Default configuration file for Watcher Decision Engine + +.. include:: footer.rst