Merge pull request #51 from appliedsec/sphinx-docs

Sphinx documentation for readthedocs.org
Fixes #50

.gitignore

@@ -9,4 +9,4 @@ pygeoip-*
 cover
 .coverage
 .coveralls.yml
-apidocs/html/.*
+docs/_build/*

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Release 0.3.1
 
+* New: Documentation now available on readthedocs.org
 * New: MaxMind Netspeed database support
 * Fix: Release thread lock on exceptions
 

DEVELOPER.md

@@ -1,5 +1,5 @@
 # Bootstrap manual for developers
-_Dependencies: tox, nose, epydoc_
+_Dependencies: tox, nose_
 
 ### Testing
 
@@ -16,19 +16,10 @@ https://www.defunct.cc/maxmind-geoip-samples.tar.gz (17 MB)
 
 Extract the tarball in the tests directory and run `tox` from the root directory.
 
-This requires a machine with Python 2.5 - 3.3 installed and all dependencies mention in the header.
-
-### Documentation
-
-The documentation can be re-generated by running epydoc from repository root.
-
-    epydoc --config=epydoc.ini --no-private
-
-For converting Markdown to reStructuredText used by PyPi we use pandoc.
-[Read pandoc's install instructions](http://johnmacfarlane.net/pandoc/installing.html).
+This requires a machine with Python 2.6 - 3.3 installed and all dependencies mention in the header.
 
 ### TL;DR
 
-There's a shell script doing all this for you.
+There's a Makefile doing all this for you.
 
-    ./build.sh
+    make test

MANIFEST.in

@@ -1,8 +1,6 @@
-recursive-include apidocs *
 recursive-include tests *
 include README.rst
 include LICENSE.md
 include DEVELOPER.md
 include CHANGELOG.md
-include epydoc.ini
 include tox.ini

Makefile

@@ -0,0 +1,24 @@
+.PHONY: docs
+
+all: test
+
+test:
+	@echo "Downloading test databases"
+	rm -rf maxmind-geoip-samples.tar.gz tests/data; mkdir -p tests/data
+	curl -s https://www.defunct.cc/maxmind-geoip-samples.tar.gz | tar -zx -C tests
+
+	@echo "Testing local state"
+	@tox --version > /dev/null || (echo "Requires tox - install requirements.txt"; exit 1)
+	tox
+
+docs:
+	@echo "Building documentation"
+	make -C docs clean
+	make -C docs html
+
+clean:
+	@echo "Cleaning doc, test and cache files"
+	git clean -fd
+	find . -name *.pyc -delete
+	rm -rf pygeoip-* pygeoip.egg-info
+

README.rst

@@ -1,8 +1,7 @@
 Pure Python GeoIP API
 =====================
 
-This library is based on `Maxmind's GeoIP C
-API <https://github.com/maxmind/geoip-api-c>`__.
+This library is based on `Maxmind's GeoIP C API <https://github.com/maxmind/geoip-api-c>`__.
 
 Tested with Python version 2.6, 2.7, 3.2 and 3.3.
 
@@ -13,7 +12,7 @@ Installation
 
 You can easily install pygeoip from PyPi.
 
-.. code:: bash
+.. code:: python
 
     pip install pygeoip
 
@@ -26,132 +25,21 @@ contribute you can always `create a pull
 request <https://github.com/appliedsec/pygeoip/pulls>`__ for discussion
 and code submission.
 
-Getting Started
----------------
-
-Create your GeoIP instance with appropriate access flag. ``STANDARD``
-reads data from disk when needed, ``MEMORY_CACHE`` loads database into
-memory on instantiation and ``MMAP_CACHE`` loads database into memory
-using mmap.
-
-.. code:: python
-
-    >>> import pygeoip
-    >>> gi = pygeoip.GeoIP('/path/to/GeoIP.dat')
-    >>> gi.country_name_by_addr('64.233.161.99')
-    'United States'
-
-Country Lookup
-~~~~~~~~~~~~~~
-
-.. code:: python
-
-    >>> gi = pygeoip.GeoIP('/path/to/GeoIP.dat')
-    >>> gi.country_code_by_name('google.com')
-    'US'
-    >>> gi.country_code_by_addr('64.233.161.99')
-    'US'
-    >>> gi.country_name_by_addr('64.233.161.99')
-    'United States'
-
-.. code:: python
-
-    >>> gi = pygeoip.GeoIP('/path/to/GeoIPv6.dat')
-    >>> gi.country_code_by_name('google.com')
-    'IE'
-    >>> gi.country_code_by_addr('2001:7fd::1')
-    'EU'
-    >>> gi.country_name_by_addr('2001:7fd::1')
-    'Europe'
-
-Region Lookup
-~~~~~~~~~~~~~
-
-.. code:: python
-
-    >>> gi = pygeoip.GeoIP('/path/to/GeoIPRegion.dat')
-    >>> gi.region_by_name('apple.com')
-    {'region_code': 'CA', 'country_code': 'US'}
-
-City Lookup
-~~~~~~~~~~~
-
-.. code:: python
-
-    >>> gi = pygeoip.GeoIP('/path/to/GeoIPCity.dat')
-    >>> gi.record_by_addr('64.233.161.99')
-    {
-        'city': u'Mountain View',
-        'region_code': u'CA',
-        'area_code': 650,
-        'time_zone': 'America/Los_Angeles',
-        'dma_code': 807,
-        'metro_code': 'San Francisco, CA',
-        'country_code3': 'USA',
-        'latitude': 37.41919999999999,
-        'postal_code': u'94043',
-        'longitude': -122.0574,
-        'country_code': 'US',
-        'country_name': 'United States',
-        'continent': 'NA'
-    }
-    >>> gi.time_zone_by_addr('64.233.161.99')
-    'America/Los_Angeles'
-
-Organization Lookup
-~~~~~~~~~~~~~~~~~~~
-
-.. code:: python
-
-    >>> gi = pygeoip.GeoIP('/path/to/GeoIPOrg.dat')
-    >>> gi.org_by_name('dell.com')
-    'Dell Computer Corporation'
-
-ISP Lookup
-~~~~~~~~~~
-
-.. code:: python
-
-    >>> gi = pygeoip.GeoIP('/path/to/GeoIPISP.dat')
-    >>> gi.isp_by_name('cnn.com')
-    'Turner Broadcasting System'
-
-ASN Lookup
-~~~~~~~~~~
-
-.. code:: python
-
-    >>> gi = pygeoip.GeoIP('/path/to/GeoIPASNum.dat')
-    >>> gi.asn_by_name('cnn.com')
-    'AS5662 Turner Broadcasting'
+Documentation
+-------------
 
-For more information, `check out the full API
-documentation <http://packages.python.org/pygeoip>`__.
+.. toctree::
+   :maxdepth: 1
 
-Supported Databases
--------------------
+   getting-started
+   supported-databases
+   api-reference
 
-+----------------+--------+--------+-----------------------------------------------------------------------------------+
-| Type           | IPv4   | IPv6   | Details                                                                           |
-+================+========+========+===================================================================================+
-| Country        | ✓      | ✓      | `MaxMind Country product page <http://www.maxmind.com/en/country>`__              |
-+----------------+--------+--------+-----------------------------------------------------------------------------------+
-| City           | ✓      | ✓      | `MaxMind City product page <http://www.maxmind.com/en/city>`__                    |
-+----------------+--------+--------+-----------------------------------------------------------------------------------+
-| Organization   | ✓      |        | `MaxMind Organization product page <http://www.maxmind.com/en/organization>`__    |
-+----------------+--------+--------+-----------------------------------------------------------------------------------+
-| ISP            | ✓      |        | `MaxMind ISP product page <http://www.maxmind.com/en/isp>`__                      |
-+----------------+--------+--------+-----------------------------------------------------------------------------------+
-| Region         | ✓      |        | `MaxMind Region product page <http://www.maxmind.com/en/geolocation_landing>`__   |
-+----------------+--------+--------+-----------------------------------------------------------------------------------+
-| ASN            | ✓      | ✓      | `MaxMind ASN product page <http://dev.maxmind.com/geoip/legacy/geolite>`__        |
-+----------------+--------+--------+-----------------------------------------------------------------------------------+
-| Netspeed       | ✓      |        | `MaxMind Netspeed product page <http://www.maxmind.com/en/netspeed>`__            |
-+----------------+--------+--------+-----------------------------------------------------------------------------------+
+For more information, `check out the documentation <http://pygeoip.readthedocs.org/>`__ over at Read the Docs.
 
 .. |Build Status| image:: https://api.travis-ci.org/appliedsec/pygeoip.png?branch=master
-   :target: https://travis-ci.org/appliedsec/pygeoip
+	:target: https://travis-ci.org/appliedsec/pygeoip
 .. |Coverage Status| image:: https://coveralls.io/repos/appliedsec/pygeoip/badge.png
-   :target: https://coveralls.io/r/appliedsec/pygeoip
+	:target: https://coveralls.io/r/appliedsec/pygeoip
 .. |Downloads| image:: https://pypip.in/d/pygeoip/badge.png
-   :target: https://crate.io/packages/pygeoip
+	:target: https://crate.io/packages/pygeoip