[ganeti/ganeti_webmgr] 9d2ec0d Clean up index, 'orphan' non-toc docs

[g...@osuosl.org]

The branch, enhancement/13785 has been updated

Old revision: b17fc2415653329cde55fd15367e9e3d78b46791, new revision: 9d2ec0dd7de06cdfc4b34ff7db76e0ab9f12a5fc.
via 9d2ec0dd7de06cdfc4b34ff7db76e0ab9f12a5fc (commit)
from b17fc2415653329cde55fd15367e9e3d78b46791 (commit)

- Log -----------------------------------------------------------------
commit 9d2ec0dd7de06cdfc4b34ff7db76e0ab9f12a5fc
Author: Kennric <ken...@hypothetical.net>
Date: Wed Mar 26 12:52:50 2014 -0700

Clean up index, 'orphan' non-toc docs

Adding :orphan: to the head of docs that are referenced by other docs but not explicitely included in a TOC prevents the "document not in any doc tree" warning.

refs #13785


Summary of changes:
docs/source/dev/developers.rst | 164 +++++++++++++++-----------------------
docs/source/dev/selenium.rst | 2 +
docs/source/dev/test_cluster.rst | 2 +
docs/source/dev/tests.rst | 6 +-
docs/source/dev/vagrant.rst | 2 +
5 files changed, 73 insertions(+), 103 deletions(-)

diff --git a/docs/source/dev/developers.rst b/docs/source/dev/developers.rst
index 847f4cb..c948f30 100644
--- a/docs/source/dev/developers.rst
+++ b/docs/source/dev/developers.rst
@@ -19,8 +19,8 @@ Please see the :ref:`issues` for details on how to create informative issues.
.. _`code.osuosl.org`: https://code.osuosl.org/projects/ganeti-webmgr


-Get the Code
-------------
+Getting the Code
+----------------

From OSL's repository:

@@ -41,54 +41,11 @@ From Github, you can `clone or fork from our repository mirror`_.

.. _`clone or fork from our repository mirror`: https://github.com/osuosl/ganeti_webmgr

-Install
--------
+Installation
+------------

To install the GWM application for development work, please see :ref:`developer_installation`

-Repository Layout
------------------
-
-We loosely follow `Git-flow <http://github.com/nvie/gitflow>`_ for managing repository. Read about the `branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_ and why `you may wish to use it too <http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/>`_.
-
-
-- **master** - Releases only, this is the main public branch.
-- **release/<version>** - A release branch, the current release branch is tagged and merged into master.
-- **develop** - Mostly stable development branch. Small changes only. It is acceptable that this branch have bugs, but should remain mostly stable.
-- **feature/<issue number>** - New features, these will be merged into develop when complete.
-- **bug/<issue number>** - Bug fixes.
-- **enhancement/<issue number>** - Enhancements to existing features.
-
-See :ref:`issues` for more information on issue types.
-
-When working on new code, be sure to create a new branch from the appropriate place:
-
-- **develop** - if this is a new feature
-- **release/<version>** - if this is a bug fix on an existing release
-
-
-Code Standards
---------------
-
-PEP8
-''''
-
-We follow `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_, "the guide for python style".
-
-In addition to PEP 8:
-
-- Do not use backslash continuations. If a line must be broken up, use parenthetical continuations instead.
-
-Units
-'''''
-
-Try to write modular code. Focus on isolating units of code that can be easily analyzed and tested. For sanity purposes, please try to avoid mutually recursive objects.
-
-JSON
-''''
-
-If you need a JSON library, the import for this code base is "from django.utils import simplejson as json". See `#6579 <http://code.osuosl.org/issues/6579>`_ for more information.
-
Dev Environment
---------------

@@ -146,98 +103,105 @@ Virtual machines provide an easy way to deploy a Ganeti cluster to test |gwm| wi
Development VM
~~~~~~~~~~~~~~

-|gwm| now ships with a Vagrantfile that will launch a headless VirtualBox vm.
-
-.. todo::
- insert information on how and why you might use this
+|gwm| now ships with a Vagrantfile that will launch a headless VirtualBox VM. See :ref:`vagrant` for details.

Test Cluster
~~~~~~~~~~~~

For instructions on setting up and using a vagrant cluster to test your code, see :ref:`test_cluster`

-Adding features
----------------
+Repository Layout
+-----------------

-When adding a feature to GWM, please remember to include:
+We loosely follow `Git-flow <http://github.com/nvie/gitflow>`_ for managing repository. Read about the `branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_ and why `you may wish to use it too <http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/>`_.

-Help tips
-'''''''''

-The gray box with a green title bar that appears on the right side of the page when you focus on a form field is a help tip. To add one for a new field, add it to the file which corresponds to your field's form in the ganeti\_web/templates/ganeti/helptips/ directory.
+- **master** - Releases only, this is the main public branch.
+- **release/<version>** - A release branch, the current release branch is tagged and merged into master.
+- **develop** - Mostly stable development branch. Small changes only. It is acceptable that this branch have bugs, but should remain mostly stable.
+- **feature/<issue number>** - New features, these will be merged into develop when complete.
+- **bug/<issue number>** - Bug fixes.
+- **enhancement/<issue number>** - Enhancements to existing features.
+
+See :ref:`issues` for more information on issue types.

-Internationalization
-''''''''''''''''''''
+When working on new code, be sure to create a new branch from the appropriate place:

-Ganeti Web Manager is designed to support translation to other languages using Django's i18n machinery. If you add text that will be displayed to the user, please remember to format it for translation:
+- **develop** - if this is a new feature
+- **release/<version>** - if this is a bug fix on an existing release

-::

- {% trans "this text will be displayed in the correct language" %}
+Code Standards
+--------------

- {% blocktrans %}
- Here is a some text that will be displayed
- in the correct language but would not
- fit well in a single line
- {% endblocktrans %}
+PEP8
+''''

-`Django's i18n page`_ has more information about this.
+We follow `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_, "the guide for python style".

-Fixing Bugs
------------
+In addition to PEP 8:

-When bugs are fixed, the issue should be updated with a clear description of the nature of the bug, the nature of the fix, and any additional notes that will help future developers understand the fix.
+- Do not use backslash continuations. If a line must be broken up, use parenthetical continuations instead.

-Before working on a bug fix, determine if the faulty code is covered by a unit test. If so, and the test did not reveal the flaw, update the test appropriately. If no test exists, it should be written if possible. The test should be submitted along with the fixed code.
+Units
+'''''
+
+Try to write modular code. Focus on isolating units of code that can be easily analyzed and tested. For sanity purposes, please try to avoid mutually recursive objects.

-Writing Tests
--------------
+JSON
+''''

-The following are general guidelines. For specific details on how to write |gwm| tests, please see See :ref:`testing`.
+If you need a JSON library, the import for this code base is "from django.utils import simplejson as json". See `#6579 <http://code.osuosl.org/issues/6579>`_ for more information.

-Ganeti Web Manager has a fairly complete test suite. New code should have matching tests. Before committing code, run the suite for Ganeti Web Manager and `Object Permissions <http://code.osuosl.org/projects/object-permissions>`_

-::
+Testing
+-------

- ./manage.py test ganeti_web
- ./manage.py test object_permissions
+Ideally, tests should be written for all code that is submitted to the project. We recommend writing a test for any new feature before writing the code.

+For bugs in features that have existing tests, be sure to run the existing tests on your code before submitting. In some cases a test will need to be updated or modified to test a bug fix, this should be done before writing code to fix the bug.

-Clean up after yourself
-'''''''''''''''''''''''
+Tests can be submitted for features separate from the feature code itself, and feature requests that are submitted along with tests will be much more likely to be implemented.

-Remember to tear down any resources you set up in your tests. Don't use "YourModel.objects.all().delete()" to clean up your objects; it could be hiding bugs. Clean up exactly the resources you created.
+See :ref:`testing` for more information on writing unit tests for Ganeti Web Manager.

-Test your setups and teardowns
-''''''''''''''''''''''''''''''
+See :ref:`selenium` for some ideas on using the Selenium web testing framework to test GWM.

-To speed up analysis of broken tests, if you have a setUp() or tearDown() in a TestCase, add a test\_trivial() method which is empty. It will pass if your setUp() and tearDown() work.

-Views
-'''''
+Adding features
+---------------

-All views should be thoroughly tested for security, checking to ensure that the proper HTTP codes are returned.
+When adding a feature to GWM, please remember to include:

-- Test Anonymous User access
-- Test Permission based access
-- Test Superuser based access
+Help tips
+'''''''''

-Check for invalid input.
+The gray box with a green title bar that appears on the right side of the page when you focus on a form field is a help tip. To add one for a new field, add it to the file which corresponds to your field's form in the ganeti\_web/templates/ganeti/helptips/ directory.

-- missing fields
-- invalid data for field
+Internationalization
+''''''''''''''''''''

-Templates & Javascript
-''''''''''''''''''''''
+Ganeti Web Manager is designed to support translation to other languages using Django's i18n machinery. If you add text that will be displayed to the user, please remember to format it for translation:

-The test suite does not yet include full selenium tests for verifying Javascript functionality. Some basic tests can be performed using Django's test suite:
+::

-- Check objects in the context: forms, lists of objects, etc.
-- Check for existence of values in forms.
+ {% trans "this text will be displayed in the correct language" %}

-See :ref:`selenium` for more information on what Selenium can test within GWM.
+ {% blocktrans %}
+ Here is a some text that will be displayed
+ in the correct language but would not
+ fit well in a single line
+ {% endblocktrans %}

+`Django's i18n page`_ has more information about this.
+
+Fixing Bugs
+-----------

+When bugs are fixed, the issue should be updated with a clear description of the nature of the bug, the nature of the fix, and any additional notes that will help future developers understand the fix.
+
+Before working on a bug fix, determine if the faulty code is covered by a unit test. If so, and the test did not reveal the flaw, update the test appropriately. If no test exists, it should be written if possible. The test should be submitted along with the fixed code.
+

Writing Documentation
---------------------

diff --git a/docs/source/dev/selenium.rst b/docs/source/dev/selenium.rst
index 71d9d96..65f1ebb 100644
--- a/docs/source/dev/selenium.rst
+++ b/docs/source/dev/selenium.rst
@@ -1,3 +1,5 @@
+:orphan:
+
.. _selenium:

Selenium test specs

diff --git a/docs/source/dev/test_cluster.rst b/docs/source/dev/test_cluster.rst
index 15dced5..8feee74 100644
--- a/docs/source/dev/test_cluster.rst
+++ b/docs/source/dev/test_cluster.rst
@@ -1,3 +1,5 @@
+:orphan:
+
.. _test_cluster:

Vagrant Test Cluster

diff --git a/docs/source/dev/tests.rst b/docs/source/dev/tests.rst
index 40970e8..f0b08df 100644
--- a/docs/source/dev/tests.rst
+++ b/docs/source/dev/tests.rst
@@ -1,11 +1,11 @@
+:orphan:
+
.. _testing:

Writing Tests
=============

-The following are general guidelines. For specific details on how to write |gwm| tests, please see See :ref:`testing`.
-
-Ganeti Web Manager has a fairly complete test suite. New code should have matching tests. Before committing code, run the suite for Ganeti Web Manager and `Object Permissions <http://code. osuosl.org/projects/object-permissions>`_
+Ganeti Web Manager has a fairly complete test suite. New code should have matching tests. Before committing code, run the suite for Ganeti Web Manager and `Object Permissions <http://code.osuosl.org/projects/object-permissions>`_

::


diff --git a/docs/source/dev/vagrant.rst b/docs/source/dev/vagrant.rst
index 91b3c46..128ecf0 100644
--- a/docs/source/dev/vagrant.rst
+++ b/docs/source/dev/vagrant.rst
@@ -1,3 +1,5 @@
+:orphan:
+
.. _vagrant:

Vagrant