Merge pull request #22 from MobilityDB/documentation

Documentation + tests3. Add tests for many classes. Add new documentation structure. Synchronize with MEOS.
MobilityDB · Oct 10, 2023 · 6cc042d · 6cc042d
2 parents 0d9610c + 48b416a
commit 6cc042d
Show file tree

Hide file tree

Showing 115 changed files with 16,568 additions and 8,291 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 .idea
 Pipfile.lock
 *-checkpoint.ipynb
+docs/_build
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,12 @@
+version: 2
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/conf.py
diff --git a/pymeos/docs/Makefile → docs/Makefile b/pymeos/docs/Makefile → docs/Makefile
diff --git a/pymeos/docs/conf.py → docs/conf.py b/pymeos/docs/conf.py → docs/conf.py
@@ -9,18 +9,20 @@
 project = 'PyMEOS'
 copyright = '2023, Víctor Diví'
 author = 'Víctor Diví'
-release = '1.1.2'
+release = '1.1.3a5'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
+
+sys.path.insert(0, os.path.abspath('../pymeos_cffi'))
+sys.path.insert(0, os.path.abspath('../pymeos'))
 
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
-    'sphinx.ext.intersphinx'
+    'sphinx.ext.intersphinx',
 ]
 
 templates_path = ['_templates']
@@ -29,17 +31,15 @@
 
 # -- Intersphinx config --------
 intersphinx_mapping = {
-    'spans': ('https://runfalk.github.io/spans/', None),
     'asyncpg': ('https://magicstack.github.io/asyncpg/current/', None),
     'psycopg': ('https://www.psycopg.org/psycopg3/docs/', None),
     'psycopg2': ('https://www.psycopg.org/docs/', None),
     'shapely': ('https://shapely.readthedocs.io/en/stable/', None),
     'python': ('https://docs.python.org/3', None)
 }
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_book_theme'
 html_static_path = ['_static']
diff --git a/doc/images/PyMEOS Layer Architecture.png → docs/images/PyMEOS Layer Architecture.png b/doc/images/PyMEOS Layer Architecture.png → docs/images/PyMEOS Layer Architecture.png
diff --git a/doc/images/PyMEOS Logo.png → docs/images/PyMEOS Logo.png b/doc/images/PyMEOS Logo.png → docs/images/PyMEOS Logo.png
diff --git a/doc/images/meos-logo.png → docs/images/meos-logo.png b/doc/images/meos-logo.png → docs/images/meos-logo.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,66 @@
+.. PyMEOS documentation master file, created by
+   sphinx-quickstart on Thu Oct  5 18:26:38 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+=======
+PyMEOS
+=======
+
+`MEOS (Mobility Engine, Open Source) <https://www.libmeos.org/>`__ is a
+C library which enables the manipulation of temporal and spatio-temporal
+data based on `MobilityDB <https://mobilitydb.com/>`__\ ’s data types
+and functions.
+
+PyMEOS is a library built on top of MEOS that provides all of its
+functionality wrapped in a set of Python classes.
+
+Requirements
+============
+
+PyMEOS 1.1 requires
+
+* Python >=3.7
+* MEOS >=1.1
+
+Installing PyMEOS
+==================
+
+We recommend installing PyMEOS using one of the available built
+distributions using ``pip``:
+
+.. code-block:: console
+
+    $ pip install pymeos
+
+See the `installation documentation <https://pymeos.readthedocs.io/en/latest/src/installation.html>`__
+for more details and advanced installation instructions.
+
+.. toctree::
+   :caption: User Guide
+   :hidden:
+
+   src/installation
+   src/manual
+   src/examples
+
+
+.. toctree::
+   :caption: API Reference
+   :hidden:
+
+   src/api/pymeos.meos_init
+   src/api/pymeos.collections
+   src/api/pymeos.temporal
+   src/api/pymeos.main
+   src/api/pymeos.boxes
+   src/api/pymeos.aggregators
+   src/api/pymeos.plotters
+   src/api/pymeos.db
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/pymeos/docs/make.bat → docs/make.bat b/pymeos/docs/make.bat → docs/make.bat
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,10 @@
+python-dateutil
+shapely
+pymeos_cffi==1.1.0a6
+asyncpg
+psycopg
+psycopg2
+matplotlib
+geopandas
+sphinx
+sphinx-book-theme
diff --git a/pymeos/docs/pymeos.aggregators.rst → docs/src/api/pymeos.aggregators.rst b/pymeos/docs/pymeos.aggregators.rst → docs/src/api/pymeos.aggregators.rst
diff --git a/pymeos/docs/pymeos.boxes.rst → docs/src/api/pymeos.boxes.rst b/pymeos/docs/pymeos.boxes.rst → docs/src/api/pymeos.boxes.rst
diff --git a/docs/src/api/pymeos.collections.base.rst b/docs/src/api/pymeos.collections.base.rst
@@ -0,0 +1,26 @@
+Base Abstract Collections
+===================
+
+Set
+-------------------------------
+
+.. automodule:: pymeos.collections.base.set
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Span
+-------------------------
+
+.. automodule:: pymeos.collections.base.span
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+SpanSet
+----------------------------
+
+.. automodule:: pymeos.collections.base.spanset
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/src/api/pymeos.collections.numeric.rst b/docs/src/api/pymeos.collections.numeric.rst
@@ -0,0 +1,53 @@
+Numeric Collections
+===================
+
+IntSet
+-----------------------
+
+.. automodule:: pymeos.collections.number.intset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+FloatSet
+-----------------------
+
+.. automodule:: pymeos.collections.number.floatset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+IntSpan
+-----------------------
+
+.. automodule:: pymeos.collections.number.intspan
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+FloatSpan
+-----------------------
+
+.. automodule:: pymeos.collections.number.floatspan
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+IntSpanSet
+-----------------------
+
+.. automodule:: pymeos.collections.number.intspanset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+FloatSpanSet
+-----------------------
+
+.. automodule:: pymeos.collections.number.floatspanset
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/src/api/pymeos.collections.rst b/docs/src/api/pymeos.collections.rst
@@ -0,0 +1,13 @@
+Collections
+===================
+
+
+.. toctree::
+   :maxdepth: 2
+
+   pymeos.collections.base
+   pymeos.collections.time
+   pymeos.collections.spatial
+   pymeos.collections.numeric
+   pymeos.collections.text
+
diff --git a/docs/src/api/pymeos.collections.spatial.rst b/docs/src/api/pymeos.collections.spatial.rst
@@ -0,0 +1,29 @@
+Spatial Collections
+===================
+
+
+GeoSet
+-----------------------
+
+.. autoclass:: pymeos.collections.geo.geoset.GeoSet
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+GeometrySet
+-----------------------
+
+.. autoclass:: pymeos.collections.geo.geoset.GeometrySet
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+GeographySet
+-----------------------
+
+.. autoclass:: pymeos.collections.geo.geoset.GeographySet
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/src/api/pymeos.collections.text.rst b/docs/src/api/pymeos.collections.text.rst
@@ -0,0 +1,10 @@
+Text Collections
+===================
+
+TextSet
+-------------------------------
+
+.. automodule:: pymeos.collections.text.textset
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/pymeos/docs/pymeos.time.rst → docs/src/api/pymeos.collections.time.rst b/pymeos/docs/pymeos.time.rst → docs/src/api/pymeos.collections.time.rst
@@ -1,34 +1,34 @@
-Time
+Time Collections
 ===================
 
 Time
 -----------------------
 
-.. automodule:: pymeos.time.time
+.. automodule:: pymeos.collections.time.time
    :members:
    :undoc-members:
    :show-inheritance:
 
-Period
--------------------------
+TimestampSet
+-------------------------------
 
-.. automodule:: pymeos.time.period
+.. automodule:: pymeos.collections.time.timestampset
    :members:
    :undoc-members:
    :show-inheritance:
 
-PeriodSet
-----------------------------
+Period
+-------------------------
 
-.. automodule:: pymeos.time.periodset
+.. automodule:: pymeos.collections.time.period
    :members:
    :undoc-members:
    :show-inheritance:
 
-TimestampSet
--------------------------------
+PeriodSet
+----------------------------
 
-.. automodule:: pymeos.time.timestampset
+.. automodule:: pymeos.collections.time.periodset
    :members:
    :undoc-members:
    :show-inheritance:
diff --git a/pymeos/docs/pymeos.db.rst → docs/src/api/pymeos.db.rst b/pymeos/docs/pymeos.db.rst → docs/src/api/pymeos.db.rst
diff --git a/pymeos/docs/pymeos.main.rst → docs/src/api/pymeos.main.rst b/pymeos/docs/pymeos.main.rst → docs/src/api/pymeos.main.rst
diff --git a/pymeos/docs/pymeos.meos_init.rst → docs/src/api/pymeos.meos_init.rst b/pymeos/docs/pymeos.meos_init.rst → docs/src/api/pymeos.meos_init.rst
diff --git a/pymeos/docs/pymeos.plotters.rst → docs/src/api/pymeos.plotters.rst b/pymeos/docs/pymeos.plotters.rst → docs/src/api/pymeos.plotters.rst
diff --git a/pymeos/docs/pymeos.temporal.rst → docs/src/api/pymeos.temporal.rst b/pymeos/docs/pymeos.temporal.rst → docs/src/api/pymeos.temporal.rst
diff --git a/docs/src/examples.rst b/docs/src/examples.rst
@@ -0,0 +1,6 @@
+Examples
+====================
+
+Section under construction. However, you can check the existing examples available in the
+`PyMEOS repository <https://github.com/MobilityDB/PyMEOS>`__ and the
+`PyMEOS-Demo repository <https://github.com/Diviloper/PyMEOS-demo>`__.