From 1ffe9457813d688201dd359fc3bc8bd6f78719e9 Mon Sep 17 00:00:00 2001 From: Paul Belanger Date: Sat, 24 Nov 2012 19:32:40 -0500 Subject: [PATCH] Create initial sphinx documentation Change-Id: I79b4d880a8bf7021bb35b240ac040d78d78e3556 Signed-off-by: Paul Belanger --- .gitignore | 2 ++ README.rst | 50 +++++++++++++++++++++++++++ doc/source/conf.py | 35 +++++++++++++++++++ doc/source/index.rst | 24 +++++++++++++ README => doc/source/installation.rst | 26 +++++++++----- setup.cfg | 4 +-- 6 files changed, 131 insertions(+), 10 deletions(-) create mode 100644 README.rst create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst rename README => doc/source/installation.rst (83%) diff --git a/.gitignore b/.gitignore index 8f35123..49789cf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ .tox build/* *.pyc +doc/build/* +doc/source/api/* diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..64fb416 --- /dev/null +++ b/README.rst @@ -0,0 +1,50 @@ +========= +GerritBot +========= + +Gerritbot is an IRC bot that will notify IRC channels of Gerrit events. + +To install:: + + $ sudo python setup.py install + +Online documentation: + + * http://ci.openstack.org/gerritbot/ + +Developers +========== + +Bug report: + + * https://bugs.launchpad.net/openstack-ci/ + +Cloning: + + * https://github.com/openstack-ci/gerritbot.git + +Patches are submitted via Gerrit at: + + * https://review.openstack.org/ + +More details on how you can contribute is available on our wiki at: + + * http://wiki.openstack.org/HowToContribute + +License +======= + +Copyright 2011 OpenStack, LLC +Copyright 2012 Hewlett-Packard Development Company, L.P. + +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. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..14a4235 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,35 @@ +# -*- coding: utf-8 -*- +# + +import sys, os + +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'GerritBot' +copyright = u'2012, OpenStack Continuous Integration Administrators' + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- 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 = 'default' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'GerritBotdoc' + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'gerritbot', u'GerritBot Documentation', + [u'OpenStack Continuous Integration Administrators'], 1) +] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..c8fd4b8 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,24 @@ +.. GerritBot documentation master file, created by + sphinx-quickstart on Sat Nov 24 19:16:10 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to GerritBot's documentation! +===================================== + +Gerritbot is an IRC bot that will notify IRC channels of Gerrit events. + +Contents: + +.. toctree:: + :maxdepth: 2 + + installation + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/README b/doc/source/installation.rst similarity index 83% rename from README rename to doc/source/installation.rst index aa4ed3f..e1766bb 100644 --- a/README +++ b/doc/source/installation.rst @@ -1,15 +1,17 @@ -Gerritbot is an IRC bot that will notify IRC channels of Gerrit events. +Installation +============ -To install Gerritbot run `python setup.py install` from within the repository's -root directory. +To install Gerritbot run :: -To run Gerritbot `$PATH/gerritbot /path/to/config`. $PATH is usually something -like /usr/local/bin and /path/to/config should be whatever path you have hidden -the config at. + sudo python setup.py install + +Configuration File +================== Gerritbot has two configuration files. The first configures the IRC server and Gerrit server details and is the config file whose path you pass to gerritbot -when starting the bot. It should look like: +when starting the bot. It should look like:: + [ircbot] nick=NICKNAME pass=PASSWORD @@ -26,7 +28,8 @@ when starting the bot. It should look like: The second configures the IRC channels and the events and projects that each channel is interested in. This config file is written in yaml and should look -like: +like:: + example-channel1: events: - patchset-created @@ -45,3 +48,10 @@ like: - example/project4 branches: - master + +Running +======= + +To run Gerritbot `$PATH/gerritbot /path/to/config`. $PATH is usually something +like /usr/local/bin and /path/to/config should be whatever path you have hidden +the config at. diff --git a/setup.cfg b/setup.cfg index 6930c85..a333b18 100644 --- a/setup.cfg +++ b/setup.cfg @@ -7,9 +7,9 @@ verbosity=2 detailed-errors=1 [build_sphinx] -source-dir = doc/source -build-dir = doc/build all_files = 1 +build-dir = doc/build +source-dir = doc/source [upload_sphinx] upload-dir = doc/build/html