Update documentation framework, add base devref details

- Add base support for devref generation to the project
- Add basic level of documentation, with TODOs for future updates
- Generate as part of tox run

Change-Id: Ic7a07ba7de0090383c652503453bafcd422a3eaa
This commit is contained in:
adreznec 2015-08-18 14:18:07 -05:00
parent be81ba4984
commit 02f9f51cef
16 changed files with 330 additions and 27 deletions

3
.gitignore vendored
View File

@ -5,4 +5,5 @@ nova_powervm.egg-info/
*.pyc
/.idea/
.coverage
/cover/
/cover/
doc/build

View File

@ -1,3 +1,5 @@
Contributing to Nova-PowerVM
============================
If you would like to contribute to the development of OpenStack,
you must follow the steps in the "If you're a developer, start here"
section of this page:

View File

@ -18,7 +18,7 @@ import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../..'))
# -- General configuration ------------------------------------------------
@ -28,7 +28,10 @@ import os
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
extensions = [
'sphinx.ext.autodoc',
'oslosphinx'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -44,7 +47,7 @@ master_doc = 'index'
# General information about the project.
project = u'nova-powervm'
copyright = u'2015, Kyle Henderson, Drew Thorstensen'
copyright = u'2015, IBM'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@ -74,11 +77,11 @@ exclude_patterns = ['_build']
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
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
add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
@ -98,7 +101,7 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
#html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -127,7 +130,7 @@ html_theme = 'default'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
#html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
@ -137,6 +140,8 @@ html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1"
html_last_updated_fmt = os.popen(git_cmd).read()
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
@ -176,7 +181,7 @@ html_static_path = ['_static']
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'nova-powervmdoc'
htmlhelp_basename = '%sdoc' % project
# -- Options for LaTeX output ---------------------------------------------
@ -196,9 +201,11 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'nova-powervm.tex', u'nova-powervm Documentation',
u'Kyle Henderson, Drew Thorstensen', 'manual'),
]
('index',
'%s.tex' % project,
u'%s Documentation' % project,
u'IBM', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
@ -226,9 +233,11 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'nova-powervm', u'nova-powervm Documentation',
[u'Kyle Henderson, Drew Thorstensen'], 1)
]
('index',
'%s' % project,
u'%s Documentation' % project,
u'IBM', 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
@ -240,10 +249,14 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'nova-powervm', u'nova-powervm Documentation',
u'Kyle Henderson, Drew Thorstensen', 'nova-powervm', 'One line description of project.',
'Miscellaneous'),
]
('index',
'%s' % project,
u'%s Documentation' % project,
u'IBM',
'%s' % project,
'An OpenStack Nova compute driver for PowerVM systems',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []

View File

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

View File

@ -0,0 +1,45 @@
..
Copyright 2015 IBM
All Rights Reserved.
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.
Setting Up a Development Environment
====================================
This page describes how to setup a working Python development
environment that can be used in developing Nova-PowerVM.
These instructions assume you're already familiar with
Git and Gerrit, which is a code repository mirror and code review toolset,
however if you aren't please see `this Git tutorial`_ for an introduction
to using Git and `this guide`_ for a tutorial on using Gerrit and Git for
code contribution to Openstack projects.
.. _this Git tutorial: http://git-scm.com/book/en/Getting-Started
.. _this guide: http://docs.openstack.org/infra/manual/developers.html#development-workflow
Getting the code
----------------
Grab the code::
git clone git://git.openstack.org/stackforge/nova-powervm
cd nova-powervm
Setting up your environment
---------------------------
.. todo::
Add in steps for environment setup

View File

@ -0,0 +1,47 @@
..
Copyright 2015 IBM
All Rights Reserved.
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.
Developer Guide
===============
In the Developer Guide, you will find information on how to develop for
Nova-PowerVM and how it interacts with Nova compute. You will also find
information on setup and usage of Nova-PowerVM
Internals and Programming
-------------------------
.. toctree::
:maxdepth: 3
development_environment
usage
Testing
-------
.. toctree::
:maxdepth: 3
testing
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@ -0,0 +1,65 @@
..
Copyright 2015 IBM
All Rights Reserved.
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.
Running Nova-PowerVM Tests
==========================
This page describes how to run the Nova-PowerVM tests. This page assumes you
have already set up an working Python environment for Nova-PowerVM development.
With `tox`
~~~~~~~~~~
Nova-PowerVM, like other OpenStack projects, uses `tox`_ for managing the virtual
environments for running test cases. It uses `Testr`_ for managing the running
of the test cases.
Tox handles the creation of a series of `virtualenvs`_ that target specific
versions of Python.
Testr handles the parallel execution of series of test cases as well as
the tracking of long-running tests and other things.
For more information on the standard tox-based test infrastructure used by
OpenStack and how to do some common test/debugging procedures with Testr,
see this wiki page:
https://wiki.openstack.org/wiki/Testr
.. _Testr: https://wiki.openstack.org/wiki/Testr
.. _tox: http://tox.readthedocs.org/en/latest/
.. _virtualenvs: https://pypi.python.org/pypi/virtualenv
PEP8 and Unit Tests
+++++++++++++++++++
Running pep8 and unit tests is as easy as executing this in the root
directory of the Nova-PowerVM source code::
tox
To run only pep8::
tox -e pep8
Since pep8 includes running pylint on all files, it can take quite some time to run.
To restrict the pylint check to only the files altered by the latest patch changes::
tox -e pep8 HEAD~1
To run only the unit tests::
tox -e py27

View File

@ -0,0 +1,22 @@
..
Copyright 2015 IBM
All Rights Reserved.
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.
Usage
=====
.. todo::
Add in steps for basic usage of nova-powervm

View File

@ -1,18 +1,44 @@
..
Copyright 2015 IBM
All Rights Reserved.
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.
Welcome to nova-powervm's documentation!
========================================
This project will provide Nova-compatible compute driver for PowerVM based
systems.
This project provides a Nova-compatible compute driver for PowerVM systems.
Documentation on Nova can be found at the `Nova Devref`_.
.. _`Nova Devref`: http://docs.openstack.org/developer/nova/devref
Nova-PowerVM Policies
=====================
Contents:
.. toctree::
:maxdepth: 2
:maxdepth: 1
policies/index
Nova-PowerVM Devref
===================
Indices and tables
==================
Contents:
* :ref:`search`
.. toctree::
:maxdepth: 1
devref/index

View File

@ -0,0 +1,26 @@
Nova-PowerVM Bugs
=================
Nova-PowerVM maintains all of its bugs in `Launchpad <https://bugs.launchpad.net/nova-powervm>`_.
All of the current open Nova-PowerVM bugs can be found in that link.
Bug Triage Process
------------------
The process of bug triaging consists of the following steps:
1. Check if a bug was filed for a correct component (project). If not, either change the project
or mark it as "Invalid".
2. Add appropriate tags. Even if the bug is not valid or is a duplicate of another one, it still
may help bug submitters and corresponding sub-teams.
3. Check if a similar bug was filed before. If so, mark it as a duplicate of the previous bug.
4. Check if the bug description is consistent, e.g. it has enough information for developers to
reproduce it. If it's not consistent, ask submitter to provide more info and mark a bug as
"Incomplete".
5. Depending on ease of reproduction (or if the issue can be spotted in the code), mark it as
"Confirmed".
6. Assign the importance. Bugs that obviously break core and widely used functionality should get
assigned as "High" or "Critical" importance. The same applies to bugs that were filed for gate
failures.
7. (Optional). Add comments explaining the issue and possible strategy of fixing/working around
the bug.

View File

@ -0,0 +1,13 @@
Code Reviews
============
Code reviews are a critical component of all OpenStack projects. Code reviews provide a
way to enforce a level of consistency across the project, and also allow for the careful
onboarding of contributions from new contributors.
Code Review Practices
---------------------
Nova-PowerVM follows the `code review guidelines <https://wiki.openstack.org/wiki/ReviewChecklist>`_ as
set forth for all OpenStack projects. It is expected that all reviewers are following the guidelines
set forth on that page.

View File

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

View File

@ -0,0 +1,40 @@
..
Copyright 2015 IBM
All Rights Reserved.
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.
Nova-PowerVM Policies
=====================
In the Policies Guide, you will find documented policies for developing with
Nova-PowerVM. This includes the processes we use for blueprints and specs,
bugs, contributor onboarding, and other procedural items.
Policies
--------
.. toctree::
:maxdepth: 3
bugs
contributing
code-reviews
readme
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

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

View File

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

View File

@ -23,6 +23,9 @@ commands = {posargs}
[testenv:cover]
commands = python setup.py testr --coverage --testr-args='{posargs}'
[testenv:docs]
commands = python setup.py build_sphinx
[flake8]
ignore = E125,E712,H104,H405,H904
exclude = .venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build,tools