From 02f9f51cefbd02ab2fa4ead3b6a9e653ccd055a3 Mon Sep 17 00:00:00 2001 From: adreznec Date: Tue, 18 Aug 2015 14:18:07 -0500 Subject: [PATCH] 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 --- .gitignore | 3 +- CONTRIBUTING.rst | 2 + doc/source/conf.py | 49 +++++++++----- doc/source/contributing.rst | 1 - doc/source/devref/development_environment.rst | 45 +++++++++++++ doc/source/devref/index.rst | 47 ++++++++++++++ doc/source/devref/testing.rst | 65 +++++++++++++++++++ doc/source/devref/usage.rst | 22 +++++++ doc/source/index.rst | 38 +++++++++-- doc/source/policies/bugs.rst | 26 ++++++++ doc/source/policies/code-reviews.rst | 13 ++++ doc/source/policies/contributing.rst | 1 + doc/source/policies/index.rst | 40 ++++++++++++ doc/source/policies/readme.rst | 1 + doc/source/readme.rst | 1 - tox.ini | 3 + 16 files changed, 330 insertions(+), 27 deletions(-) delete mode 100644 doc/source/contributing.rst create mode 100644 doc/source/devref/development_environment.rst create mode 100644 doc/source/devref/index.rst create mode 100644 doc/source/devref/testing.rst create mode 100644 doc/source/devref/usage.rst create mode 100644 doc/source/policies/bugs.rst create mode 100644 doc/source/policies/code-reviews.rst create mode 100644 doc/source/policies/contributing.rst create mode 100644 doc/source/policies/index.rst create mode 100644 doc/source/policies/readme.rst delete mode 100644 doc/source/readme.rst diff --git a/.gitignore b/.gitignore index 9815746c..0a49a85d 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,5 @@ nova_powervm.egg-info/ *.pyc /.idea/ .coverage -/cover/ \ No newline at end of file +/cover/ +doc/build diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 28586948..b6809f1a 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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: diff --git a/doc/source/conf.py b/doc/source/conf.py index d2f905d3..06cbf141 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 = [] diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index ac7b6bcf..00000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/devref/development_environment.rst b/doc/source/devref/development_environment.rst new file mode 100644 index 00000000..d55af588 --- /dev/null +++ b/doc/source/devref/development_environment.rst @@ -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 diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst new file mode 100644 index 00000000..149cb09c --- /dev/null +++ b/doc/source/devref/index.rst @@ -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` + diff --git a/doc/source/devref/testing.rst b/doc/source/devref/testing.rst new file mode 100644 index 00000000..dab6db61 --- /dev/null +++ b/doc/source/devref/testing.rst @@ -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 diff --git a/doc/source/devref/usage.rst b/doc/source/devref/usage.rst new file mode 100644 index 00000000..6c4d2e19 --- /dev/null +++ b/doc/source/devref/usage.rst @@ -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 diff --git a/doc/source/index.rst b/doc/source/index.rst index bbef7be1..6b0fc7b4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/policies/bugs.rst b/doc/source/policies/bugs.rst new file mode 100644 index 00000000..1934e4f1 --- /dev/null +++ b/doc/source/policies/bugs.rst @@ -0,0 +1,26 @@ +Nova-PowerVM Bugs +================= + +Nova-PowerVM maintains all of its bugs in `Launchpad `_. +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. diff --git a/doc/source/policies/code-reviews.rst b/doc/source/policies/code-reviews.rst new file mode 100644 index 00000000..a78d6894 --- /dev/null +++ b/doc/source/policies/code-reviews.rst @@ -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 `_ as +set forth for all OpenStack projects. It is expected that all reviewers are following the guidelines +set forth on that page. + diff --git a/doc/source/policies/contributing.rst b/doc/source/policies/contributing.rst new file mode 100644 index 00000000..b1cd2f37 --- /dev/null +++ b/doc/source/policies/contributing.rst @@ -0,0 +1 @@ +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/policies/index.rst b/doc/source/policies/index.rst new file mode 100644 index 00000000..22c6cf70 --- /dev/null +++ b/doc/source/policies/index.rst @@ -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` + diff --git a/doc/source/policies/readme.rst b/doc/source/policies/readme.rst new file mode 100644 index 00000000..e4a3ad51 --- /dev/null +++ b/doc/source/policies/readme.rst @@ -0,0 +1 @@ +.. include:: ../../../README.rst diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3d..00000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/tox.ini b/tox.ini index 738abaa4..af6edf96 100644 --- a/tox.ini +++ b/tox.ini @@ -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