Doc generation support

Based on cookiecutter and slightly tweaked afterward.

* conf.py has autoclass_content = 'both' to generate the __init__
  documentation.
* bumped doc copyright to 2015.
* adds in tox environement 'docs' as a convenience

Change-Id: I69bb4179be343ab7c8a44f6fb80d5a428fe30e17
This commit is contained in:
Antoine Musso 2014-05-22 15:24:28 +02:00
parent 10a9ca52bc
commit 207357ea9e
13 changed files with 161 additions and 17 deletions

2
.gitignore vendored
View File

@ -6,6 +6,8 @@ build/*
*.pyc
gerritlib/versioninfo
doc/build/*
# pbr generates these
AUTHORS
ChangeLog

View File

@ -15,3 +15,21 @@ Pull requests submitted through GitHub will be ignored.
Bugs should be filed on StoryBoard, not GitHub:
https://storyboard.openstack.org/#!/project/718
To browse the latest code:
https://git.openstack.org/cgit/openstack-infra/gerritlib/tree/
To clone the latest code:
git clone git://git.openstack.org/openstack-infra/gerritlib
Code reviews are handled by gerrit:
http://review.openstack.org
Use `git review` to submit patches (after creating a gerrit
account that links to your launchpad account). Example::
# Do your commits
$ git review
# Enter your username if prompted

View File

@ -2,20 +2,3 @@ gerritlib
=========
A Python library for interacting with Gerrit.
Contributing
------------
To browse the latest code, see: https://git.openstack.org/cgit/openstack-infra/gerritlib/tree/
To clone the latest code, use `git clone git://git.openstack.org/openstack-infra/gerritlib`
Bugs are handled at: https://storyboard.openstack.org/#!/project/718
Code reviews are, as you might expect, handled by gerrit. The gerrit they
use is http://review.openstack.org
Use `git review` to submit patches (after creating a gerrit account that links to your launchpad account). Example::
# Do your commits
$ git review
# Enter your username if prompted

6
doc/source/api.rst Normal file
View File

@ -0,0 +1,6 @@
API
===
.. automodule:: gerritlib.gerrit
:members:
:undoc-members:

78
doc/source/conf.py Executable file
View File

@ -0,0 +1,78 @@
# -*- coding: utf-8 -*-
# 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.
import os
import sys
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',
]
# Document both class and __init__ methods.
# http://sphinx-doc.org/ext/autodoc.html#confval-autoclass_content
autoclass_content = 'both'
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable
# The suffix of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'gerritlib'
copyright = u'2012-2015, OpenStack Foundation'
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = True
# 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. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# html_static_path = ['static']
# Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index',
'%s.tex' % project,
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}

View File

@ -0,0 +1,4 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst

20
doc/source/index.rst Normal file
View File

@ -0,0 +1,20 @@
Welcome to gerritlib's documentation!
========================================================
Contents:
.. toctree::
:maxdepth: 2
readme
api
installation
usage
contributing
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@ -0,0 +1,12 @@
============
Installation
============
At the command line::
$ pip install gerritlib
Or, if you have virtualenvwrapper installed::
$ mkvirtualenv gerritlib
$ pip install gerritlib

1
doc/source/readme.rst Normal file
View File

@ -0,0 +1 @@
.. include:: ../../README.rst

7
doc/source/usage.rst Normal file
View File

@ -0,0 +1,7 @@
========
Usage
========
To use gerritlib in a project::
import gerritlib

View File

@ -15,3 +15,11 @@ classifier =
Programming Language :: Python :: 2
Programming Language :: Python :: 2.7
Programming Language :: Python :: 2.6
[build_sphinx]
source-dir = doc/source
build-dir = doc/build
all_files = 1
[upload_sphinx]
upload-dir = doc/build/html

View File

@ -1 +1,3 @@
hacking>=0.5.6,<0.8
sphinx>=1.1.2

View File

@ -12,6 +12,9 @@ commands = flake8
[testenv:pyflakes]
commands = flake8
[testenv:docs]
commands = python setup.py build_sphinx
[testenv:venv]
commands = {posargs}