Permalink
Browse files

Merge branch 'feat/documentation'

* 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.
  • Loading branch information...
JNRowe committed Feb 28, 2012
2 parents 6724850 + 04b2497 commit 8bc7dde9da25973c39bb2225c00518601ec31ef3
Showing with 113 additions and 11 deletions.
  1. +4 −4 doc/api/core.rst
  2. +3 −3 doc/contributing.rst
  3. +1 −0 doc/index.rst
  4. +63 −0 doc/release.rst
  5. +40 −2 github2/core.py
  6. +1 −1 tests/test_tz_aware_date_handling.py
  7. +1 −1 tests/utils.py
View
@@ -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()
View
@@ -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
View
@@ -41,6 +41,7 @@ Contents
bugs
contributing
wild
+ release
license
Indices and tables
View
@@ -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
View
@@ -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__,
@@ -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())
View
@@ -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.

0 comments on commit 8bc7dde

Please sign in to comment.