moved freq_to_band to pyhamtools.frequency; short callsigns in other countries (e.g. C6A/9H5A) are now correctly decoded; improved documentation

docs/source/Callinfo.rst

@@ -1,10 +0,0 @@
-Callinfo
-========
-
-.. toctree::
-   :maxdepth: 2
-
-.. automodule:: pyhamtools.callinfo
-
-.. autoclass:: Callinfo
-    :members:

docs/source/LookupLib.rst

@@ -1,10 +0,0 @@
-LookupLib
-=========
-
-.. toctree::
-   :maxdepth: 2
-
-.. automodule:: pyhamtools.lookuplib
-
-.. autoclass:: LookupLib
-    :members:

docs/source/changelog.rst

@@ -0,0 +1,22 @@
+Changelog
+---------
+
+PyHamTools 0.4.1
+================
+
+27. September 2014
+
+ * short calls in different countries (e.g. 9H3A/C6A) are now decoded correctly
+
+ * added pyhamtools.frequency
+
+ * moved pyhamtools.utils.freq_to_band into pyhamtools.frequency
+
+ * deprecated module pyhamtools.utils
+
+PyHamTools 0.4.0
+================
+
+20. September 2014
+
+ * Added module for locator based calculations (pyhamtools.locators)

docs/source/conf.py

@@ -60,7 +60,7 @@ copyright = u'2014, Tobias Wellnitz, DH1TW'
 # The short X.Y version.
 version = '0.4'
 # The full version, including alpha/beta/rc tags.
-release = '0.4.0'
+release = '0.4.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/examples.rst

@@ -0,0 +1,80 @@
+
+Examples
+========
+
+Almost each class / function in the reference section has an example. For the sake of convenience, some examples are shown below to give you a quick understanding how PyHamTools work.
+
+Calculate Shortpath and Longpath Heading between two locators
+-------------------------------------------------------------
+
+.. code-block:: none
+
+   >>> from pyhamtools.locator import calculate_heading, calculate_heading_longpath
+   >>> calculate_heading("JN48QM", "QF67bf")
+   74.3136
+   
+   >>> calculate_heading_longpath("JN48QM", "QF67bf")
+   254.3136
+
+
+Calculate Distance between two WGS84 Coordinates
+------------------------------------------------
+
+.. code-block:: none
+
+   >>> from pyhamtools.locator import calculate_distance, latlong_to_locator
+   >>> locator1 = latlong_to_locator(48.52, 9.375)
+   >>> locator2 = latlong_to_locator(-32.77, 152.125)
+   >>> distance = calculate_heading(locator1, locator2)
+   >>> print("%.1fkm" % distance)
+   16466.4km
+   
+Calculate Sunrise and Sunset for JN48QM on the 1. January 2015
+--------------------------------------------------------------
+
+
+.. code-block:: none
+
+   >>> from pyhamtools.locator import calculate_sunrise_sunset
+   >>> from datetime import datetime
+   >>> my_locator = "JN48QM"
+   >>> my_date = datetime(year=2015, month=1, day=1)
+   >>> data = calculate_sunrise_sunset(my_locator, my_date)
+   >>> print "Sunrise: " + data['sunrise'].strftime("%H:%MZ") + ", Sunset: " + data['sunset'].strftime("%H:%MZ")
+   Sunrise: 07:14Z, Sunset: 16:15Z
+
+
+Decode a Callsign and get Country name, ADIF ID, Latitude & Longitude
+---------------------------------------------------------------------
+
+In this example we will use AD1C's Country-files.com database to perform the lookup.
+
+First we need to instanciate a LookupLib object for Country-files.com database. The latest database will be downloaded automatically.
+
+.. code-block:: none
+
+   >>> from pyhamtools import LookupLib, Callinfo
+   >>> my_lookuplib = LookupLib(lookuptype="countryfile")
+   
+   
+Next, a Callinfo class needs to be instanciated. The lookuplib object will be injected on construction.
+
+.. code-block:: none
+
+   >>> cic = Callinfo(my_lookuplib)
+
+
+Now we can query the information conveniently through our Callinfo object:
+
+.. code-block:: none
+
+   >>> cic.get_all("DH1TW")
+   {
+       'country': 'Fed. Rep. of Germany',
+       'adif': 230,
+       'continent': 'EU',
+       'latitude': 51.0,
+       'longitude': -10.0,
+       'cqz': 14,
+       'ituz': 28
+   }

docs/source/index.rst

@@ -12,34 +12,36 @@
 :IRC:           #hamtests on webirc.deltaxray.org
 
 PyHamTools is a Python library which helps you creating Amateur Radio applications faster. It comes
-with some modules and classes which are frequently needed, like locator based calculations (distance,
-heading, etc) or parsing of Amateur Radio callsigns. 
+with some modules and classes which are frequently needed: 
 
-Currently, PyHamtools contains the following modules and classes:
+ - Locator based calculations (distance, heading, sunrise/sunset, Locator to Lat/Long conversion)
 
-Modules
-^^^^^^^
-.. toctree::
-   :maxdepth: 2
+ - Checking frequencies against the IARU bandplan or 
 
-   utils
-   locator
+ - Parsing Amateur Radio callsigns using Clublog.org_'s or AD1C's Country-Files.com_ database
 
-Clases
-^^^^^^
+PyHamTools is used in production at the DXHeat.com DXCluster_, performing several thousand lookups and calculations per day.
+
+.. _Clublog.org: https://secure.clublog.org/
+.. _Country-Files.com: http://www.country-files.com/
+
+.. _DXCluster: https://dxheat.com
+
+PyHamTools Documentation
+========================
+
+Contents: 
 
 .. toctree::
    :maxdepth: 2
 
-   Callinfo
-   LookupLib
-
-
+   reference
+   examples
+   changelog
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 

docs/source/locator.rst

@@ -1,8 +0,0 @@
-locator
-=======
-
-.. toctree::
-   :maxdepth: 2
-
-.. automodule:: pyhamtools.locator
-    :members:

docs/source/reference.rst

@@ -0,0 +1,39 @@
+
+Reference
+=========
+
+pyhamtools.locator
+------------------
+
+.. module:: pyhamtools.locator
+
+.. automodule:: pyhamtools.locator
+    :members:
+
+pyhamtools.frequency
+--------------------
+
+.. automodule:: pyhamtools.frequency
+    :members:
+    
+pyhamtools.callinfo
+-------------------
+
+.. automodule:: pyhamtools.callinfo
+
+.. autoclass:: Callinfo
+    :members:
+
+pyhamtools.lookuplib
+--------------------
+
+.. automodule:: pyhamtools.lookuplib
+
+.. autoclass:: LookupLib
+    :members:
+    
+pyhamtools.utils (deprecated)
+-----------------------------
+
+.. automodule:: pyhamtools.utils
+    :members:

docs/source/utils.rst

@@ -1,8 +0,0 @@
-utils
-=====
-
-.. toctree::
-   :maxdepth: 2
-
-.. automodule:: pyhamtools.utils
-    :members: