#1 Work in progress:

- Update and imporve existing documentation
- Add Analysing section
- Reorgabise methods for GPX and Gpx objects

[ci skip]

docs/source/description.rst

@@ -9,9 +9,16 @@ Description
 
 .. image:: https://img.shields.io/pypi/dm/ezGPX
 
-Easy to use Python GPX library.
+.. note:: TLDR: Easy to use Python library for GPX files.
 
+ezGPX is an open source Python library that provides an application programming interface to interact with GPX files. GPS eXchange Format (GPX) is an open file format widely used to share location data. Geographical coordinates (latitude and longitude) from GPS and accompanying relevant data (such as time or elevation) are arranged in an XML file following a specific schema. Initialy proposed by TopoGraphix in 2002, this schema orders GPS points to create tracks and routes while providing support for metadata and extensions.
+
+ezGPX links:
 - PyPi: https://pypi.org/project/ezgpx/
 - Documentation: https://ezgpx.readthedocs.io/en/latest/
 - Source code: https://github.com/FABallemand/ezGPX
-- Bug reports: https://github.com/FABallemand/ezGPX/issues
+- Bug reports: https://github.com/FABallemand/ezGPX/issues
+
+Related links:
+- TopoGraphix: https://www.topografix.com/
+- The GPS Exchange Format: https://www.topografix.com/gpx.asp

docs/source/installation.rst

@@ -1,8 +1,6 @@
 Installation
 ============
 
-.. warning:: In order to use advanced plotting features, ezgpx uses gmplot and folium.
-
 Install ezGPX with :command:`pip`::
 
     python3 -m pip install --upgrade pip

docs/source/tutorials/analysing.rst

@@ -0,0 +1,169 @@
+Analysing
+---------
+
+ezGPX provides many insights about the GPS contained in the file.
+
+Name
+^^^^
+
+The name of the activity is easily accessible and editable using the :py:meth:`~name` and :py:meth:`~set_name` methods.
+
+::
+
+    from ezgpx import GPX
+
+    # Parse GPX file
+    gpx = GPX("file.gpx")
+
+    # Print name
+    print(gpx.name())
+
+    # Change name
+    gpx.set_name("New name")
+
+Points
+^^^^^^
+
+ezGPX provides access to information related to points and their coordinates such as:
+* The number of points
+* The bounds (ie: minimum and maximum latitude and longitude)
+* The coordinates of the center
+* The first and last point
+* The extreme points (ie: the points at which minimum and maximum latitude and longitude are reached)
+
+::
+
+    from ezgpx import GPX
+
+    # Parse GPX file
+    gpx = GPX("file.gpx")
+
+    # Compute number of points
+    nb_pts = gpx.nb_points()
+
+    # Compute bounds
+    min_lat, min_lon, max_lat, max_lon = gpx.bounds()
+
+    # Compute center
+    center_lat, center_lon = gpx.center()
+
+    # Retrieve first/last point
+    first_pt = gpx.first_point()
+    last_pt = gpx.last_point()
+
+    # Retrieve extreme points
+    min_lat_pt, min_lon_pt, max_lat_pt, max_lon_pt = gpx.extreme_points()
+
+Distance and Elevation
+^^^^^^^^^^^^^^^^^^^^^^
+
+There are several methods to compute insights related to distance and elevation. The total distance of the track is easily accessible using the :py:meth:`~distance` method. The other methods related to ascent and descent (rates) requires the :py:class:`~ezgpx.gpx.GPX` to contain elevation data.
+
+.. note:: Distances are expressed in metres (m) and rates in percentage (%).
+
+::
+
+    from ezgpx import GPX
+
+    # Parse GPX file
+    gpx = GPX("file.gpx")
+
+    # Compute distance
+    dist = gpx.distance()
+
+    # Compute ascent
+    ascent = gpx.ascent()
+
+    # Compute descent
+    descent = gpx.descent()
+
+    # Compute minimum/maximum altitude
+    min_ele = gpx.min_elevation()
+    max_ele = gpx.max_elevation()
+
+    # Compute ascent rate at each point
+    # Note: this function is executed by all methods that require
+    # ascent rate of points
+    gpx.compute_points_ascent_rate()
+
+    # Compute minimum/maximum ascent rate
+    min_ascent_rate = gpx.min_ascent_rate()
+    max_ascent_rate = gpx.max_ascent_rate()
+
+Time
+^^^^
+
+If a :py:class:`~ezgpx.gpx.GPX` object contains time related data (mainly time-stamp at each point), many useful informations can be accessed.
+
+::
+
+    from ezgpx import GPX
+
+    # Parse GPX file
+    gpx = GPX("file.gpx")
+
+    # Retrieve start/stop time
+    start_time = gpx.start_time()
+    stop_time = gpx.stop_time()
+
+    # Compute the total amount of time elapsed
+    elapsed_time = gpx.total_elapsed_time()
+
+    # Compute the total amount of time stopped
+    elapsed_time = gpx.stopped_time()
+
+    # Compute the total amount of time spent moving
+    elapsed_time = gpx.moving_time()
+
+Speed and Pace
+^^^^^^^^^^^^^^
+
+If a :py:class:`~ezgpx.gpx.GPX` object contains time related data (mainly time-stamp at each point), it is possible to gain speed and pace insights. Furthermore, if elevation data are also available, ascent speeds can be computed!
+
+.. note:: Speeds are expressed in kilometres per hour (km/h) and paces in minutes per kilometre (min/km).
+
+::
+
+    from ezgpx import GPX
+
+    # Parse GPX file
+    gpx = GPX("file.gpx")
+
+    # Compute average speed
+    avg_speed = gpx.avg_speed()
+
+    # Compute average speed while moving
+    avg_speed = gpx.avg_moving_speed()
+
+    # Compute speed at each point
+    # Note: this function is executed by all methods that require
+    # speed at each point
+    gpx.compute_points_speed()
+
+    # Retrieve minimum/maximum speed reached at a point
+    min_speed = gpx.min_speed()
+    max_speed = gpx.max_speed()
+
+    # Compute average pace
+    avg_pace = gpx.avg_pace()
+
+    # Compute average pace while moving
+    avg_pace = gpx.avg_moving_pace()
+
+    # Compute pace at each point
+    # Note: this function is executed by all methods that require
+    # pace at each point
+    gpx.compute_points_pace()
+
+    # Retrieve minimum/maximum pace reached at a point
+    min_pace = gpx.min_pace()
+    max_pace = gpx.max_pace()
+
+    # Compute ascent_speed at each point
+    # Note: this function is executed by all methods that require
+    # ascent speed at each point
+    gpx.compute_points_ascent_speed()
+
+    # Retrieve minimum/maximum ascent speed reached at a point
+    min_ascent_speed = gpx.min_ascent_speed()
+    max_ascent_speed = gpx.max_ascent_speed()

docs/source/tutorials/index.rst

@@ -6,6 +6,7 @@ Tutorials
   :maxdepth: 2
 
   parsing.rst
+  analysing.rst
   plotting.rst
   modifying.rst
   writing.rst

docs/source/tutorials/modifying.rst

@@ -4,7 +4,7 @@ Modifying
 Remove Data
 ^^^^^^^^^^^
 
-All data contained in a GPX file are not always relevant. By working with :py:class:`~ezgpx.gpx.GPX` objects, it is possible to remove useless data such as metadata, elevation and time data.
+Not all the data contained in a GPX file is always relevant. With :py:class:`~ezgpx.gpx.GPX` objects, it is possible to remove unused data such as metadata, elevation and time data, as well as all data contained in extensions. This is particularily useful when using devices with limited storage space or computing power. A GPX file of a 10 km run downloaded from Strava weighing 345.4 kB can be reduced to a 52.5 kB file (ie: only 15.2 % of the original file size).
 
 ::
 
@@ -22,31 +22,16 @@ All data contained in a GPX file are not always relevant. By working with :py:cl
     # Remove time data
     gpx.remove_time()
 
-    # Write new simplified GPX file
-    gpx.to_gpx("new_file.gpx")
-
-Remove GPS Errors
-^^^^^^^^^^^^^^^^^
-
-GPS devices sometimes loose signal generating errors in GPX files. The most noticeable errors (single isolated points) can be found and removed as follow.
-
-::
-
-    import ezgpx
-
-    # Parse GPX file
-    gpx = ezgpx.GPX("file.gpx")
-
-    # Remove GPS errors
-    gpx.remove_gps_errors()
+    # Remove extensions data
+    gpx.remove_extensions()
 
     # Write new simplified GPX file
     gpx.to_gpx("new_file.gpx")
 
 Simplify Track
 ^^^^^^^^^^^^^^
 
-It is sometimes usefull to reduce the amount of track points contained in a GPX file especially when working with low power and low capacity GPS devices. The :py:meth:`~simplify` allows to reduce the number of points while keeping a great precision.
+It is sometimes usefull to reduce the amount of track points contained in a GPX file especially when dealing with low power or low capacity devices. The :py:meth:`~simplify` method reduces the number of points while maintaining good precision.
 
 ::
 
@@ -61,7 +46,7 @@ It is sometimes usefull to reduce the amount of track points contained in a GPX
     # Write new simplified GPX file
     gpx.to_gpx("new_file.gpx")
 
-In the following example, one manage to go from 3263 track points to only 1082. This correspond to a 69% decrease in points and allows to save 704.6 kB (ie: 85.4% of the original file size) by reducing the file size from 824.8 kB to 120.2 kB.
+In the following example, a 42 km run downloaded from Strava went from 3263 track points to only 1082. This correspond to a 69% decrease in points and allows to save 704.6 kB (ie: 85.4 % of the original file size) by reducing the file size from 824.8 kB to 120.2 kB.  It is clear that the algorithm used only removes points that do not provide significant information preserving the shape of the track.
 
 ::
 
@@ -90,4 +75,22 @@ In the following example, one manage to go from 3263 track points to only 1082.
 
 .. image:: ../../../img/simplify_1.png
   :width: 500
-  :alt: Track plot followed by the simplified track plot
+  :alt: Track plot followed by the simplified track plot
+
+Remove GPS Errors
+^^^^^^^^^^^^^^^^^
+
+GPS devices sometimes lose signal generating errors in GPX files. The most noticeable errors (single isolated points) can be found and removed as follow.
+
+::
+
+    import ezgpx
+
+    # Parse GPX file
+    gpx = ezgpx.GPX("file.gpx")
+
+    # Remove GPS errors
+    gpx.remove_gps_errors()
+
+    # Write new simplified GPX file
+    gpx.to_gpx("new_file.gpx")

docs/source/tutorials/parsing.rst

@@ -6,33 +6,29 @@ GPX Files
 
 In order to parse a GPX file, simply create a new :py:class:`~ezgpx.gpx.GPX` object with the path to the file.
 
-.. note::
-
-    In the next tutorials you will learn how to plot, modify and save this :py:class:`~ezgpx.gpx.GPX` object.
+.. note:: In the next tutorials you will learn how to plot, modify and save this :py:class:`~ezgpx.gpx.GPX` object to a file.
 
 ::
 
-    from ezGPX import GPX
+    import ezgpx
 
     # Parse GPX file
-    gpx = GPX("file.gpx")
+    gpx = ezgpx.GPX("file.gpx")
 
 
 KML Files
 ^^^^^^^^^
 
 In order to parse a KML file, simply create a new :py:class:`~ezgpx.gpx.GPX` object with the path to the file.
 
-.. note::
-
-    This method is mainly designed to perform a simple conversion from KML to GPX. To that extent, only GPS data from the KML files will be processed.
+.. note:: This method is mainly designed to perform a simple conversion from KML to GPX. To that extent, only GPS data from the KML files will be processed.
 
 ::
 
-    from ezGPX import GPX
+    import ezgpx
 
     # Parse KML file
-    gpx = GPX("file.kml")
+    gpx = ezgpx.GPX("file.kml")
 
 
 KMZ Files
@@ -41,20 +37,16 @@ KMZ Files
 KML files are commonly distributed as KMZ files, which are zipped KML files with a .kmz extension.
 In order to parse a KMZ file, simply create a new :py:class:`~ezgpx.gpx.GPX` object with the path to the file.
 
-.. note::
-
-    This method will create a temporary KML file in the working directory.
-
-.. note::
+.. note:: This method will create a temporary KML file in the working directory.
 
-    This method is mainly designed to perform a simple conversion from KMZ to GPX. To that extent, only GPS data from the one of the KML files found in the KMZ will be processed.
+.. note:: This method is mainly designed to perform a simple conversion from KMZ to GPX. To that extent, only GPS data from the one of the KML files found in the KMZ will be processed.
 
 ::
 
-    from ezGPX import GPX
+    import ezgpx
 
     # Parse KMZ file
-    gpx = GPX("file.kmz")
+    gpx = ezgpx.GPX("file.kmz")
 
 
 FIT Files
@@ -64,7 +56,7 @@ In order to parse a FIT file, simply create a new :py:class:`~ezgpx.gpx.GPX` obj
 
 ::
 
-    from ezGPX import GPX
+    import ezgpx
 
     # Parse FIT file
-    gpx = GPX("file.fit")
+    gpx = ezgpx.GPX("file.fit")

docs/source/tutorials/plotting.rst

@@ -3,6 +3,8 @@ Plotting
 
 ezGPX currently provides many different ways to plot a :py:class:`~ezgpx.gpx.GPX` object.
 
+.. warning:: These features are likely to be deprecated and removed in future versions.
+
 Matplotlib
 ^^^^^^^^^^