Pull Changes from develop for documentation updates

README.rst

@@ -7,25 +7,38 @@ envector
 
 
 The envector library is a suite of tools written in Python to solve geographical position calculations. This is
-an open-source fork of the original nvector_ Python package based on the MATLAB nvector `MATLAB n-vector toolbox`_.
-
-Currently the following operations are implemented:
-
-* Calculate the surface distance between two geographical positions.
-
-* Convert positions given in one reference frame into another reference frame.
-
-* Find the destination point given start point, azimuth/bearing and distance.
-
-* Find the mean position (center/midpoint) of several geographical positions.
-
-* Find the intersection between two paths.
-
-* Find the cross track distance between a path and a position.
+an open-source fork of the original nvector_ Python package based on the `MATLAB n-vector toolbox`_.
 
+Explanation of Intent
+=====================
 
-Using envector, the calculations become simple and non-singular.
-Full accuracy is achieved for any global position (and for any distance).
+This is a Python package that will assist you in calculating the distance between two points anywhere on, above, or
+below the Earth's surface. This can also be between two, three, or many points. This is quite useful in many areas from
+logistics, tracking, navigation, data analytics, data science, and research. The calculations are simple and
+non-singular. Full accuracy is achieved for any global position (and for any distance).
+
+Use Cases
+=========
+
+A use case in logistics is when you need to recommend to your customers the closest facilities or store
+locations given an address or GPS coordinates. Your customers usually provide an address and you can convert that to GPS
+coordinates, or geographic location in latitude and longitude. Given this information, you need to recommend the closest
+locations and approximate distance in kilometers (km) or miles. You can implement the Haversine formula, which is a
+reasonable estimate if you are concerned with relatively short distances less than 100 km. However, you might meed to be
+aware of the difference in altitudes between two locations. On top of all that, the Haversine formula is not accurate
+for longer distances as the Earth is not exactly a sphere. You can properly account for all these issues using our
+envector_ package.
+
+Another use case is for navigation and tracking. Imagine that you
+have a vehicle like a ship, airplane, or off-road vehicle on a fixed course. The vehicle has an unreliable and
+inaccurate GPS unit, and it is your job to ensure that the vehicle stays on course. This makes your job much harder if
+you want to minimize the trip duration and vehicle fuel to maximize the number of trips possible for the day.
+Fortunately, the envector_ package can help you 1) aggregate measurements to estimate the mean position, 2) interpolate
+the next expected position in a fixed time interval, and 3) determine if the vehicle is veering off-course by measuring
+the cross-track distance from the intended path.
+
+These use cases and more are well supported by the envector_ package. We encourage you to check out the
+examples below to help you maximize the utility of envector_.
 
 Questions and Answers
 =====================
@@ -53,9 +66,23 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t
 
 4. *What changes are there with from nvector*?
 
-    * Any place there is a `import nvector` or `from nvector` statement, replace it with `import envector` or
-      `from envector`, respectively.
-    * The envector_ package is a Python3-only package as it embraces type-hints in most cases.
+    * The major difference is the namespace. Any place where your project have statements like:
+
+       .. code-block:: python
+            :caption: Importing the nvector package
+
+            import nvector as nv
+            from nvector import GeoPoint
+
+      You would replace them:
+
+        .. code-block:: python
+            :caption: Importing the envector package instead
+
+            import envector as nv
+            from envector import GeoPoint
+
+    * The envector_ package is a Python3-only package as it embraces static typing in most cases.
     * Documentation is expanded in some cases.
     * The docstrings have been refactored to utilize the Napoleon docstring style.
 
@@ -64,10 +91,93 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t
     * If your Python software must support NumPy version 2,
     * If your Python software also stops supporting Python versions after its end-of-life cycle.
 
+6. *How do I make the switch to envector*?
+
+    * If your project utilizes CPython3.9 through 3.12, inclusive, then you can simply change your `requirements.txt`,
+      `environment.yml`, `pyproject.toml`, or `setup.py` file to specify envector_.
+
+        .. code-block:: text
+            :caption: `requirements.txt` format
+
+            # requirements.txt format
+            envector>=0
+
+        .. code-block:: yaml
+            :caption: Anaconda `environment.yml` format
+
+            # environment.yml format
+            - pip:
+              - envector>=0
 
+        .. code-block:: toml
+            :caption: `pyproject.toml` format
+
+            # pyproject.toml format
+            # PEP 508 compliant
+            [project]
+            dependencies = [
+                "envector>=0"
+            ]
+
+            # Poetry (not PEP 508 compliant)
+            [tool.poetry.dependencies]
+            envector = ">=0"
+
+        .. code-block:: python
+            :caption: `setup.py` format
+
+            # setup.py format
+            install_requires=['envector>=0',
+                              ...
+                              ]
+
+        * Your Python code will now need to import envector_
+
+    * If your project uses anything less than CPython3.9, then it depends on how your project is specified. If you are
+      using `pyproject.toml` or `setup.py`, then the changes are relatively simple as shown below. The other common
+      Anaconda `environment.yml` and `requirements.txt` formats require you to pick one depending on the Python
+      version. For Python2 to 3.8, you cannot use envector_.
+
+        .. code-block:: toml
+            :caption: `pyproject.toml` format to specify both nvector and envector
+
+            # pyproject.toml format
+            # PEP 508 compliant
+            [project]
+            dependencies = [
+                "envector>=0; python_version >= '3.9'",
+                "nvector>=0; python_version < '3.9'",
+            ]
+
+            # Poetry (not PEP 508 compliant)
+            [tool.poetry.dependencies]
+            envector = { version = ">=0", python = ">=3.9" }
+            nvector = { version = ">=0", python = "<3.9" }
+
+        .. code-block:: python
+            :caption: `setup.py` format to specify both nvector and envector
+
+            # setup.py format
+            install_requires=['envector>=0; python_version >= "3.9"',
+                              'nvector>=0; python_version < "3.9"',
+                              ...
+                              ]
+
+        * Your Python code will now need to try and import envector_ or nvector_ in a try-except block.
+
+            .. code-block:: python
+                :caption: Code block to import either nvector or envector
+
+                    # Code block to import either nvector or envector
+                    try:
+                        import nvector as nv
+                    except (ImportError,):
+                        import envector as nv
+
+
+Technical Description
+=====================
 
-Description
-===========
 In this library, we represent position with an "n-vector",  which
 is the normal vector to the Earth model (the same reference ellipsoid that is
 used for latitude and longitude). When using n-vector, all Earth-positions are
@@ -136,7 +246,7 @@ Then at the Python prompt, try to import envector:
 
     >>> import envector as nv
     >>> print(nv.__version__)
-    0.2.0
+    0.3.1
 
 
 To test if the toolbox is working correctly paste the following in an interactive
@@ -146,8 +256,10 @@ python session::
    nv.test('--doctest-modules')
 
 
-Getting Started
-===============
+.. _examples:
+
+Getting Started with Examples
+=============================
 
 Below the object-oriented solution to some common geodesic problems are given.
 In the first example the functional solution is also given.
@@ -629,7 +741,7 @@ to do the calculations.
 .. _nvector downloads: https://www.ffi.no/en/research/n-vector/n-vector-downloads
 .. _MATLAB n-vector toolbox: https://github.com/FFI-no/n-vector
 .. |pkg_img| image:: https://badge.fury.io/py/envector.svg
-   :target: https://pypi.python.org/pypi/envector/
+   :target: https://badge.fury.io/py/envector
 .. |docs_img| image:: https://readthedocs.org/projects/pip/badge/?version=stable
    :target: http://envector.readthedocs.org/en/stable/
 .. |versions_img| image:: https://img.shields.io/pypi/pyversions/envector.svg

docs/index.rst

@@ -14,6 +14,38 @@ Official releases are available at: http://pypi.python.org/pypi/envector.
 Official homepage are available at: http://www.navlab.net/nvector/
 
 
+Explanation of Intent
+---------------------
+
+This is a Python package that will assist you in calculating the distance between two points anywhere on, above, or
+below the Earth's surface. This can also be between two, three, or many points. This is quite useful in many areas from
+logistics, tracking, navigation, data analytics, data science, and research. The calculations are simple and
+non-singular. Full accuracy is achieved for any global position (and for any distance).
+
+Use Cases
+---------
+
+A use case in logistics is when you need to recommend to your customers the closest facilities or store
+locations given an address or GPS coordinates. Your customers usually provide an address and you can convert that to GPS
+coordinates, or geographic location in latitude and longitude. Given this information, you need to recommend the closest
+locations and approximate distance in kilometers (km) or miles. You can implement the Haversine formula, which is a
+reasonable estimate if you are concerned with relatively short distances less than 100 km. However, you might meed to be
+aware of the difference in altitudes between two locations. On top of all that, the Haversine formula is not accurate
+for longer distances as the Earth is not exactly a sphere. You can properly account for all these issues using our
+envector_ package.
+
+Another use case is for navigation and tracking. Imagine that you
+have a vehicle like a ship, airplane, or off-road vehicle on a fixed course. The vehicle has an unreliable and
+inaccurate GPS unit, and it is your job to ensure that the vehicle stays on course. This makes your job much harder if
+you want to minimize the trip duration and vehicle fuel to maximize the number of trips possible for the day.
+Fortunately, the envector_ package can help you 1) aggregate measurements to estimate the mean position, 2) interpolate
+the next expected position in a fixed time interval, and 3) determine if the vehicle is veering off-course by measuring
+the cross-track distance from the intended path.
+
+These use cases and more are well supported by the envector_ package. We encourage you to check out the
+:doc:`/tutorials/index` to help you maximize the utility of envector_.
+
+
 Questions and Answers
 ---------------------
 
@@ -40,9 +72,23 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t
 
 4. *What changes are there with from nvector*?
 
-    * Any place there is a `import nvector` or `from nvector` statement, replace it with `import envector` or
-      `from envector`, respectively.
-    * The envector_ package is a Python3-only package as it embraces type-hints in most cases.
+    * The major difference is the namespace. Any place where your project have statements like:
+
+       .. code-block:: python
+            :caption: Importing the nvector package
+
+            import nvector as nv
+            from nvector import GeoPoint
+
+      You would replace them:
+
+        .. code-block:: python
+            :caption: Importing the envector package instead
+
+            import envector as nv
+            from envector import GeoPoint
+
+    * The envector_ package is a Python3-only package as it embraces static typing in most cases.
     * Documentation is expanded in some cases.
     * The docstrings have been refactored to utilize the Napoleon docstring style.
 
@@ -51,6 +97,86 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t
     * If your Python software must support NumPy version 2,
     * If your Python software also stops supporting Python versions after its end-of-life cycle.
 
+6. *How do I make the switch to envector*?
+
+    * If your project utilizes CPython3.9 through 3.12, inclusive, then you can simply change your `requirements.txt`,
+      `environment.yml`, `pyproject.toml`, or `setup.py` file to specify envector_.
+
+        .. code-block:: text
+            :caption: `requirements.txt` format
+
+            envector>=0
+
+        .. code-block:: yaml
+            :caption: Anaconda `environment.yml` format
+
+            - pip:
+              - envector>=0
+
+        .. code-block:: toml
+            :caption: `pyproject.toml` format
+
+            # PEP 508 compliant
+            [project]
+            dependencies = [
+                "envector>=0"
+            ]
+
+            # Poetry (not PEP 508 compliant)
+            [tool.poetry.dependencies]
+            envector = ">=0"
+
+        .. code-block:: python
+            :caption: `setup.py` format
+
+            install_requires=['envector>=0',
+                              ...
+                              ]
+
+        * Your Python code will now need to import envector_
+
+            .. code-block:: python
+                :caption: Importing envector into your module
+
+                    import envector as nv
+
+    * If your project uses anything less than CPython3.9, then it depends on how your project is specified. If you are
+      using `pyproject.toml` or `setup.py`, then the changes are relatively simple as shown below. The other common
+      Anaconda `environment.yml` and `requirements.txt` formats require you to pick one depending on the Python
+      version. For Python2 to 3.8, you cannot use envector_.
+
+        .. code-block:: toml
+            :caption: `pyproject.toml` format to specify both nvector and envector
+
+            # PEP 508 compliant
+            [project]
+            dependencies = [
+                "envector>=0; python_version >= '3.9'",
+                "nvector>=0; python_version < '3.9'",
+            ]
+
+            # Poetry (not PEP 508 compliant)
+            [tool.poetry.dependencies]
+            envector = { version = ">=0", python = ">=3.9" }
+            nvector = { version = ">=0", python = "<3.9" }
+
+        .. code-block:: python
+            :caption: `setup.py` format to specify both nvector and envector
+
+            install_requires=['envector>=0; python_version >= "3.9"',
+                              'nvector>=0; python_version < "3.9"',
+                              ...
+                              ]
+
+        * Your Python code will now need to import both envector_ and nvector_
+
+            .. code-block:: python
+                :caption: Code block to import either nvector or envector
+
+                    try:
+                        import nvector as nv
+                    except (ImportError,):
+                        import envector as nv
 
 
 .. toctree::

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "envector"
 dynamic = ["version"]
-description = "The envector library is a suite of tools written in Python to solve geographical position calculations forked from nvector."
+description = "The envector package is a suite of tools written in Python forked from the nvector package to solve geographical position calculations powered by means of n-vector."
 authors = [
     {name = "Matt Hogan", email = "mhogan@nwra.com"},
     {name = "Kenneth Gade, FFI"},

src/envector/_images.py

@@ -2,7 +2,7 @@
 .. only:: html
 
     .. |pkg_img| image:: https://badge.fury.io/py/envector.svg
-       :target: https://pypi.python.org/pypi/envector/
+       :target: ttps://badge.fury.io/py/envector
 
     .. |docs_img| image:: https://readthedocs.org/projects/pip/badge/?version=stable
        :target: http://envector.readthedocs.org/en/stable/

src/envector/_intro.py

@@ -26,8 +26,9 @@
 
 
 
-Description
-===========
+Technical Description
+=====================
+
 In this library, we represent position with an "n-vector",  which
 is the normal vector to the Earth model (the same reference ellipsoid that is
 used for latitude and longitude). When using n-vector, all Earth-positions are