Documentation improvements

Author: oschwald

docs/conf.py

@@ -50,9 +50,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '.01'
+version = geoip2.__version__
 # The full version, including alpha/beta/rc tags.
-release = '.01'
+release = geoip2.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

geoip2/errors.py

@@ -8,7 +8,7 @@
 class GeoIP2Error(RuntimeError):
     """There was a generic error in GeoIP2.
 
-    This class represents a generic error. It extends ``RuntimeError``
+    This class represents a generic error. It extends :py:exc:`RuntimeError`
     and does not add any additional attributes.
 
     """
@@ -18,7 +18,7 @@ class GeoIP2HTTPError(GeoIP2Error):
     """There was an error when making your HTTP request.
 
     This class represents an HTTP transport error. It extends 
-    ``GeoIP2Error`` and adds attributes of its own.
+    :py:exc:`GeoIP2Error` and adds attributes of its own.
 
     :ivar http_status: The HTTP status code returned
     :ivar uri: The URI queried
@@ -33,7 +33,7 @@ class GeoIP2WebServiceError(GeoIP2HTTPError):
     """The GeoIP2 web service returned an error.
 
     This class represents an error returned by MaxMind's GeoIP2 Precision
-    web service. It extends ``GeoIP2HTTPError``.
+    web service. It extends :py:exc:`GeoIP2HTTPError`.
 
     :ivar http_status: The HTTP status code returned
     :ivar uri: The URI queried

geoip2/models.py

@@ -19,16 +19,16 @@ class Country(object):
     This class provides the following methods, each of which returns a record
     object.
 
-    :ivar continent: Returns a ``geoip2.records.Continent`` object
+    :ivar continent: :py:class:`geoip2.records.Continent` object
       representing continent data for the requested IP address.
-    :ivar country: Returns a ``geoip2.recordsCountry`` object representing
+    :ivar country: :py:class:`geoip2.recordsCountry` object representing
       country data for the requested IP address. This record represents the
       country where MaxMind believes the IP is located in.
-    :ivar registered_country: Returns a ``geoip2.recordsCountry`` object
+    :ivar registered_country: :py:class:`geoip2.recordsCountry` object
       representing the registered country data for the requested IP address.
       This record represents the country where the ISP has registered a given
       IP block in and may differ from the user's country.
-    :ivar traits: Returns ``a geoip2.records.Traits`` object representing
+    :ivar traits: :py:class:`geoip2.records.Traits` object representing
       the traits for the request IP address.
 
     """
@@ -52,22 +52,22 @@ def __init__(self, raw_response, languages=None):
 class City(Country):
     """Model class for the GeoIP2 Precision City end point
 
-    :ivar city: Returns a ``geoip2.records.City`` object representing
+    :ivar city: :py:class:`geoip2.records.City` object representing
       country data for the requested IP address.
-    :ivar continent: Returns a ``geoip2.records.Continent`` object
+    :ivar continent: :py:class:`geoip2.records.Continent` object
       representing continent data for the requested IP address.
-    :ivar country: Returns a ``geoip2.recordsCountry`` object representing
+    :ivar country: :py:class:`geoip2.recordsCountry` object representing
       country data for the requested IP address. This record represents the
       country where MaxMind believes the IP is located in.
-    :ivar location: Returns a ``geoip2.records.Location`` object
+    :ivar location: :py:class:`geoip2.records.Location` object
       representing country data for the requested IP address.
-    :ivar region: Returns a ``geoip2.records.Region`` object representing
+    :ivar region: :py:class:`geoip2.records.Region` object representing
       country data for the requested IP address.
-    :ivar registered_country: Returns a ``geoip2.recordsCountry`` object
+    :ivar registered_country: :py:class:`geoip2.recordsCountry` object
       representing the registered country data for the requested IP address.
       This record represents the country where the ISP has registered a given
       IP block in and may differ from the user's country.
-    :ivar traits: Returns ``a geoip2.records.Traits`` object representing
+    :ivar traits: :py:class:`geoip2.records.Traits` object representing
       the traits for the request IP address.
 
 """
@@ -85,22 +85,22 @@ def __init__(self, raw_response, languages=None):
 class CityISPOrg(City):
     """Model class for the GeoIP2 Precision City/ISP/Org end point
 
-    :ivar city: Returns a ``geoip2.records.City`` object representing
+    :ivar city: :py:class:`geoip2.records.City` object representing
       country data for the requested IP address.
-    :ivar continent: Returns a ``geoip2.records.Continent`` object
+    :ivar continent: :py:class:`geoip2.records.Continent` object
       representing continent data for the requested IP address.
-    :ivar country: Returns a ``geoip2.recordsCountry`` object representing
+    :ivar country: :py:class:`geoip2.recordsCountry` object representing
       country data for the requested IP address. This record represents the
       country where MaxMind believes the IP is located in.
-    :ivar location: Returns a ``geoip2.records.Location`` object
+    :ivar location: :py:class:`geoip2.records.Location` object
       representing country data for the requested IP address.
-    :ivar region: Returns a ``geoip2.records.Region`` object representing
+    :ivar region: :py:class:`geoip2.records.Region` object representing
       country data for the requested IP address.
-    :ivar registered_country: Returns a ``geoip2.recordsCountry`` object
+    :ivar registered_country: :py:class`geoip2.recordsCountry` object
       representing the registered country data for the requested IP address.
       This record represents the country where the ISP has registered a given
       IP block in and may differ from the user's country.
-    :ivar traits: Returns ``a geoip2.records.Traits`` object representing
+    :ivar traits: :py:class:`geoip2.records.Traits` object representing
       the traits for the request IP address.
 
     """
@@ -109,22 +109,22 @@ class CityISPOrg(City):
 class Omni(CityISPOrg):
     """Model class for the GeoIP2 Precision Omni end point
 
-    :ivar city: Returns a ``geoip2.records.City`` object representing
+    :ivar city: :py:class:`geoip2.records.City` object representing
       country data for the requested IP address.
-    :ivar continent: Returns a ``geoip2.records.Continent`` object
+    :ivar continent: :py:class:`geoip2.records.Continent` object
       representing continent data for the requested IP address.
-    :ivar country: Returns a ``geoip2.recordsCountry`` object representing
+    :ivar country: :py:class:`geoip2.recordsCountry` object representing
       country data for the requested IP address. This record represents the
       country where MaxMind believes the IP is located in.
-    :ivar location: Returns a ``geoip2.records.Location`` object
+    :ivar location: :py:class:`geoip2.records.Location` object
       representing country data for the requested IP address.
-    :ivar region: Returns a ``geoip2.records.Region`` object representing
+    :ivar region: :py:class:`geoip2.records.Region` object representing
       country data for the requested IP address.
-    :ivar registered_country: Returns a ``geoip2.recordsCountry`` object
+    :ivar registered_country: :py:class:`geoip2.recordsCountry` object
       representing the registered country data for the requested IP address.
       This record represents the country where the ISP has registered a given
       IP block in and may differ from the user's country.
-    :ivar traits: Returns ``a geoip2.records.Traits`` object representing
+    :ivar traits: :py:class:`geoip2.records.Traits` object representing
       the traits for the request IP address.
 
     """

geoip2/webservices.py

@@ -118,27 +118,25 @@ class Client(object):
       passed onto record classes to use when their name properties are
       called. The default value is ['en'].
 
-    Details on language handling:
+      The order of the languages is significant. When a record class has
+      multiple names (country, city, etc.), its name property will return
+      the name in the first language that has one.
 
-    The order of the languages is significant. When a record class has
-    multiple names (country, city, etc.), its name property will return
-    the name in the first language that has one.
+      Note that the only language which is always present in the GeoIP2
+      Precision data in "en". If you do not include this language, the 
+      name property may end up returning None even when the record hass
+      an English name.
 
-    Note that the only language which is always present in the GeoIP2
-    Precision data in "en". If you do not include this language, the 
-    name property may end up returning None even when the record hass
-    an English name.
+      Currently, the valid list of language codes is:
 
-    Currently, the valid list of language codes is:
+      * en -- English names may still include accented characters if that is
+        the accepted spelling in English. In other words, English does not
+        mean ASCII.
+      * ja -- Japanese
+      * ru -- Russian
+      * zh-CN -- Simplified Chinese.
 
-    * en -- English names may still include accented characters if that is
-      the accepted spelling in English. In other words, English does not
-      mean ASCII.
-    * ja -- Japanese
-    * ru -- Russian
-    * zh-CN -- Simplified Chinese.
-
-    Passing any other language code will result in an error.
+      Passing any other language code will result in an error.
 
     """