Prepare for 0.9 release by cleaning up documentation

docs/HISTORY.txt

@@ -6,7 +6,7 @@ Changelog
 -----------------
 
 - Add tox.ini for running tests using tox [Ian Lee]
-- Add PyPy and PyPy3 to travis cofiguration
+- Add documentation, hosted at https://fastkml.readthedocs.org [Ian Lee]
 
 0.8 (2014/09/18)
 -----------------

docs/index.rst

@@ -13,10 +13,8 @@ Welcome to FastKML's documentation!
 .. image:: https://www.ohloh.net/p/fastkml/widgets/project_thin_badge.gif
     :target: https://www.ohloh.net/p/fastkml
 
-Introduction
-------------
 
-fastkml is a library to read, write and manipulate kml files. It aims to keep
+Fastkml is a library to read, write and manipulate kml files. It aims to keep
 it simple and fast (using lxml_ if available). "Fast" refers to the time you
 spend to write and read KML files as well as the time you spend to get
 aquainted to the library or to create KML objects. It provides a subset of KML
@@ -34,7 +32,7 @@ Rationale
 Why yet another KML library? None of the existing ones quite fitted my
 requirements, namely:
 
-* fastkml can *read and write* KML files, feeding fastkmls output back into
+* Fastkml can *read and write* KML files, feeding fastkmls output back into
   fastkml   and serializing it again will result in the same output.
 * You can parse any kml snipppet, it does not need to be a complete KML
   document.

docs/installing.rst

@@ -3,7 +3,7 @@ Installation
 
 fastkml works with CPython version 2.6, 2.7, 3.2, 3.3, 3.4 and is
 continually tested with TravisCI for these version. The tests break
-intermittently for pypy and pypy3 so they are not tested but should work,
+intermittently for pypy and pypy3 so they are not tested but *should* work,
 Jython and IronPython are not tested but *should* work.
 
 .. image:: https://api.travis-ci.org/cleder/fastkml.png
@@ -13,10 +13,11 @@ fastkml works on Unix/Linux, OS X, and Windows.
 
 Install it with ``pip install fastkml`` or ``easy_install fastkml``.
 
-If you use it extensively or need to process big kml files consider
+If you use fastkml extensively or need to process big kml files consider
 installing lxml_ as it speeds up processing.
 
-You can install all of the requirements for working with fastkml by using pip_::
+You can install all requirements for working with fastkml by using pip_ from
+the base of the source tree::
 
     pip install -r requirements.txt
 

docs/reference_guide.rst

@@ -2,40 +2,44 @@
 Reference Guide
 ===============
 
-Modules
-=======
-
-atom
-----
+Atom
+====
 
 .. automodule:: fastkml.atom
+    :members:
 
-base
-----
+Base
+====
 
 .. automodule:: fastkml.base
+    :members:
 
-config
-------
+Config
+======
 
 .. automodule:: fastkml.config
+    :members:
 
-geometry
---------
+Geometry
+========
 
 .. automodule:: fastkml.geometry
+    :members:
 
-gx
---
+GX
+==
 
 .. automodule:: fastkml.gx
+    :members:
 
-kml
----
+KML
+===
 
 .. automodule:: fastkml.kml
+    :members:
 
-styles
-------
+Styles
+======
 
 .. automodule:: fastkml.styles
+    :members:

docs/usage_guide.rst

@@ -2,7 +2,7 @@ Usage Guide
 ===========
 
 
-You can find more examples in the included tests.py file or in
+You can find more examples in the included ``test_main.py`` file or in
 collective.geo.fastkml_, here is a quick overview:
 
 

fastkml/__init__.py

 # -*- coding: utf-8 -*-
 # Copyright (C) 2012  Christian Ledermann
-
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
-
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
-
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+#
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
 from .kml import KML, Document, Folder, Placemark
 from .kml import TimeSpan, TimeStamp
@@ -25,3 +25,16 @@ from .styles import IconStyle, LineStyle, PolyStyle
 from .styles import LabelStyle, BalloonStyle
 
 from .atom import Link, Author, Contributor
+
+__version__ = '0.9'
+
+__all__ = [
+    'KML', 'Document', 'Folder', 'Placemark',
+    'TimeSpan', 'TimeStamp',
+    'ExtendedData', 'Data',
+    'Schema', 'SchemaData',
+    'StyleUrl', 'Style', 'StyleMap',
+    'IconStyle', 'LineStyle', 'PolyStyle',
+    'LabelStyle', 'BalloonStyle',
+    'Link', 'Author', 'Contributor',
+]

fastkml/atom.py

 # -*- coding: utf-8 -*-
 # Copyright (C) 2012  Christian Ledermann
+#
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
-
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
-
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 """
-KML 2.2 supports new elements for including data about the author and
-related website in your KML file. This information is displayed in geo
-search results, both in Earth browsers such as Google Earth, and in other
-applications such as Google Maps. The ascription elements used in KML
-are as follows:
+KML 2.2 supports new elements for including data about the author and related
+website in your KML file. This information is displayed in geo search results,
+both in Earth browsers such as Google Earth, and in other applications such as
+Google Maps. The ascription elements used in KML are as follows:
 
 atom:author element - parent element for atom:name
 atom:name element - the name of the author
@@ -29,8 +29,9 @@ href attribute - URL of the web page containing the KML/KMZ file
 These elements are defined in the Atom Syndication Format. The complete
 specification is found at http://atompub.org.
 
-This library only  implements a subset of Atom that is useful with KML
+This library only implements a subset of Atom that is useful with KML
 """
+
 import logging
 logger = logging.getLogger('fastkml.atom')
 

fastkml/base.py

 # -*- coding: utf-8 -*-
 # Copyright (C) 2012  Christian Ledermann
 #
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
 #
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
 #
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
-""" abstract base classes"""
+"""Abstract base classes"""
 
 import fastkml.config as config
 from fastkml.config import etree

fastkml/config.py

 # -*- coding: utf-8 -*-
 # Copyright (C) 2012  Christian Ledermann
 #
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
 #
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
 #
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+
+"""Frequently used constants and configuration options"""
 
-"""frequently used constants and abstract base classes"""
 import logging
 logger = logging.getLogger('fastkml.config')
 

fastkml/geometry.py

 # -*- coding: utf-8 -*-
 # Copyright (C) 2012  Christian Ledermann
 #
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
 #
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
 #
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+
 """
-Import the geometries from shapely if it is installed
-or otherwise from Pygeoif
+Import the geometries from shapely if it is installed or otherwise from Pygeoif
 """
+
 try:
     from shapely.geometry import Point, LineString, Polygon
     from shapely.geometry import MultiPoint, MultiLineString, MultiPolygon

fastkml/gx.py

 # -*- coding: utf-8 -*-
 # Copyright (C) 2012  Christian Ledermann
 #
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
 #
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
 #
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
 """
 With the launch of Google Earth 5.0, Google has provided extensions to KML
 to support a number of new features. These extensions use the gx prefix
-and the following namespace URI:
+and the following namespace URI::
 
     xmlns:gx="http://www.google.com/kml/ext/2.2"
 
 This namespace URI must be added to the <kml> element in any KML file
-using gx-prefixed elements:
+using gx-prefixed elements::
 
-    <kml xmlns="http://www.opengis.net/kml/2.2"
-    xmlns:gx="http://www.google.com/kml/ext/2.2">
+    <kml
+        xmlns="http://www.opengis.net/kml/2.2"
+        xmlns:gx="http://www.google.com/kml/ext/2.2"
+    >
 
 Extensions to KML may not be supported in all geo-browsers. If your
 browser doesn't support particular extensions, the data in those
@@ -77,7 +79,3 @@ located at http://developers.google.com/kml/schema/kml22gx.xsd.
 
 import logging
 logger = logging.getLogger('fastkml.gx')
-
-# from .config import etree
-# from .config import GXNS as NS
-# from .config import LXML

fastkml/kml.py

 # -*- coding: utf-8 -*-
 # Copyright (C) 2012  Christian Ledermann
 #
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
 #
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
 #
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
 """
 KML is an open standard officially named the OpenGIS KML Encoding Standard

fastkml/styles.py

 # -*- coding: utf-8 -*-
 # Copyright (C) 2012  Christian Ledermann
 #
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
 #
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
 #
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+
 """
 Once you've created features within Google Earth and examined the KML
 code Google Earth generates, you'll notice how styles are an important

fastkml/test_main.py

 # -*- coding: utf-8 -*-
 # Copyright (C) 2012  Christian Ledermann
 #
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
 #
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
 #
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
 try:
     import unittest2 as unittest  # Needed in Python 2.6

setup.py

@@ -3,6 +3,8 @@ from setuptools.command.test import test as TestCommand
 import sys
 import os
 
+import fastkml
+
 
 class PyTest(TestCommand):
     def finalize_options(self):
@@ -17,11 +19,9 @@ class PyTest(TestCommand):
         sys.exit(errno)
 
 
-version = '0.9'
-
 setup(
     name='fastkml',
-    version=version,
+    version=fastkml.__version__,
     description="Fast KML processing in python",
     long_description=(
         open("README.rst").read() + "\n" +