Merge branch 'feat/documentation'

JNRowe · JNRowe · commit 8bc7dde9da25 · 2012-02-28T20:18:54.000Z
* feat/documentation:
  Fixed Sphinx :see: uses to use domain refs.
  Added basic release building document.
  [QA] Missing word in contributing.
  Initial documentation for the binding objects.
diff --git a/doc/api/core.rst b/doc/api/core.rst
@@ -30,10 +30,10 @@ Core
 
 .. autofunction:: repr_string
 
-.. autoclass:: GithubCommand(type)
+.. autoclass:: GithubCommand
 
-.. autoclass:: Attribute(type)
+.. autoclass:: Attribute
 
-.. autoclass:: DateAttribute(type)
+.. autoclass:: DateAttribute(help, format)
 
-.. autoclass:: BaseDataType(type)
+.. autoclass:: BaseData()
diff --git a/doc/contributing.rst b/doc/contributing.rst
@@ -71,9 +71,9 @@ Many assertions, such as :meth:`~unittest.TestCase.assertIn` and
 The simple workaround is to evaluate an expression to test with
 :meth:`~unittest.TestCase.assertTrue`
 
-The incredibly functions for skipping tests(:func:`~unittest.skip`) and marking
-expected failures(:func:`~unittest.expectedFailure`) were only added in 2.7, and
-unfortunately can't be used.
+The incredibly useful functions for skipping tests(:func:`~unittest.skip`) and
+marking expected failures(:func:`~unittest.expectedFailure`) were only added in
+2.7, and unfortunately can't be used.
 
 .. todo::
    Add topic branches and pull request usage examples, but most git users are
diff --git a/doc/index.rst b/doc/index.rst
@@ -41,6 +41,7 @@ Contents
    bugs
    contributing
    wild
+   release
    license
 
 Indices and tables
diff --git a/doc/release.rst b/doc/release.rst
@@ -0,0 +1,63 @@
+Release HOWTO
+=============
+
+.. highlight:: sh
+
+..
+  Much of this stuff is automated locally, but I'm describing the process for
+  other people who will not have access to the same release tools I use.  The
+  first thing I recommend that you do is find/write a tool that allows you to
+  automate all of this, or you're going to miss important steps at some point.
+
+Test
+----
+
+In the general case tests can be run via :pypi:`nose`'s :pypi:`distribute`
+integration::
+
+    $ ./setup.py nosetests
+
+When preparing a release it is important to check that :mod:`github2` works with
+all currently supported Python versions, and that the documentation is correct.
+To that end you can use :pypi:`tox` to run the full testsuite::
+
+    $ tox -v
+
+This will test :mod:`github2` with Python 2.4 → 3.2, check that the ``reST``
+syntax is valid and also that the :pypi:`sphinx` documentation builds correctly.
+You can run a subset of these options too, see the ``tox`` documentation for
+more information.
+
+Prepare release
+---------------
+
+With the tests passing, perform the following steps
+
+* Update the version data in :file:`github2/_version.py`, and also the
+  reference in :file:`README.rst`
+* Update :file:`NEWS.rst`, if there are any user visible changes
+* Commit the release notes and version changes
+* Create a signed tag for the release
+* Push the changes, including the new tag, to the GitHub repository
+
+Update PyPI
+-----------
+
+..
+  This is the section you're especially likely to get wrong at some point if you
+  try to handle all of this manually ;)
+
+Create and upload the new release tarballs to PyPI::
+
+    $ ./setup.py sdist --formats=bztar,gztar register upload --sign
+
+You should also update the hosted documentation too::
+
+    $ ./setup.py build_sphinx && ./setup.py upload_docs
+
+Fetch the uploaded tarballs, and check for errors.
+
+You should also perform test installations from PyPI, to check the experience
+:mod:`github2` users will have.
+
+.. highlight:: python
diff --git a/github2/core.py b/github2/core.py
@@ -137,9 +137,24 @@ def enhanced_by_auth(f):
 class GithubCommand(object):
 
     def __init__(self, request):
+        """Main API binding interface
+
+        :param github2.request.GithubRequest request: HTTP request handler
+        """
         self.request = request
 
     def make_request(self, command, *args, **kwargs):
+        """Make an API request
+
+        Various options are supported if they exist in ``kwargs``:
+
+        * The value of a ``method`` argument will define the HTTP method
+          to perform for this request, the default is ``GET``
+        * The value of a ``filter`` argument will restrict the response to that
+          data
+        * The value of a ``page`` argument will be used to fetch a specific
+          page of results, default of 1 is assumed if not given
+        """
         filter = kwargs.get("filter")
         post_data = kwargs.get("post_data") or {}
         page = kwargs.pop("page", 1)
@@ -162,6 +177,11 @@ def make_request(self, command, *args, **kwargs):
         return response
 
     def get_value(self, *args, **kwargs):
+        """Process a single-value response from the API
+
+        If a ``datatype`` parameter is given it defines the
+        :class:`BaseData`-derived class we should build from the provided data
+        """
         datatype = kwargs.pop("datatype", None)
         value = self.make_request(*args, **kwargs)
         if datatype:
@@ -176,6 +196,10 @@ def get_value(self, *args, **kwargs):
         return value
 
     def get_values(self, *args, **kwargs):
+        """Process a multi-value response from the API
+
+        :see: :meth:`get_value`
+        """
         datatype = kwargs.pop("datatype", None)
         values = self.make_request(*args, **kwargs)
         if datatype:
@@ -208,8 +232,11 @@ def bullet(title, text):
 
 
 class Attribute(object):
-
     def __init__(self, help):
+        """Generic object attribute for use with :class:`BaseData`
+
+        :param str help: Attribute description
+        """
         self.help = help
 
     def to_python(self, value):
@@ -228,6 +255,11 @@ class DateAttribute(Attribute):
     }
 
     def __init__(self, *args, **kwargs):
+        """Date handling attribute for use with :class:`BaseData`
+
+        :param str format: The date format to support, see
+            :data:`convertor_for_format` for supported options
+        """
         self.format = kwargs.pop("format", self.format)
         super(DateAttribute, self).__init__(*args, **kwargs)
 
@@ -280,6 +312,12 @@ def iterate(self):
 # Ugly base class definition for Python 2 and 3 compatibility, where metaclass
 # syntax is incompatible
 class BaseData(BaseDataType('BaseData', (object, ), {})):
+    """Wrapper for API responses
+
+    .. warning::
+       Supports subscript attribute access purely for backwards compatibility,
+       you shouldn't rely on that functionality in new code
+    """
     def __getitem__(self, key):
         """Access objects's attribute using subscript notation
 
@@ -296,7 +334,7 @@ def __getitem__(self, key):
     def __setitem__(self, key, value):
         """Update object's attribute using subscript notation
 
-        :see: ``BaseData.__getitem__``
+        :see: :meth:`BaseData.__getitem__`
         """
         LOGGER.warning("Subscript access on %r is deprecated, use object "
                        "attributes" % self.__class__.__name__,
diff --git a/tests/test_tz_aware_date_handling.py b/tests/test_tz_aware_date_handling.py
@@ -23,7 +23,7 @@ def teardown_module():
 def dt_utz(year, month, day, hour, minute, second):
     """Produce a UTC-anchored datetime object
 
-    :see: ``datetime.datetime``
+    :see: :class:`datetime.datetime`
     """
     return dt(year, month, day, hour, minute, second, tzinfo=tzutc())
 
diff --git a/tests/utils.py b/tests/utils.py
@@ -73,7 +73,7 @@ class HttpMockAuthenticatedTestCase(HttpMockTestCase):
     def setUp(self):
         """Prepare test fixtures
 
-        :see: ``HttpMockTestCase``
+        :see: :class:`HttpMockTestCase`
 
         :attr:`client` is an authenticated :obj:`Github` object for easy use
         in tests.
