Add documentation and tests (#34)

* add python tests

* added doc

* added notebooks

* jupyter lite in progresss

* added test notebooks

* change notebooks

* notebooks

* Heatmap notebooks

* change te title in docs

* added notebooks examples for github

* jupyter lite + python block for geotiff

* Delete jupyter lite files

* remove jupyter lite file

* deteled extra file

* fixed doc

* documentation improved

* Update Playwright Snapshots

* Iterate on the docs and the jupyterlite build

* Iterate

* Rework docs

* Iterate

* Iterate

* Pin Python

* Update Playwright Snapshots

* More gentle test

* Add action to build the docs

* Fix package name

* Fix default shell + deps

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: martinRenou <[email protected]>

Author: 3 people

Diff for: .github/workflows/build.yml

@@ -6,6 +6,10 @@ on:
   pull_request:
     branches: '*'
 
+defaults:
+  run:
+    shell: bash -l {0}
+
 jobs:
   build:
     runs-on: ${{ matrix.os }}
@@ -40,6 +44,20 @@ jobs:
           name: dist ${{ github.run_number }}
           path: ./dist
 
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - uses: mamba-org/setup-micromamba@v1
+        with:
+          environment-file: docs/build-environment.yml
+
+      - name: Build
+        run: sphinx-build . output
+        working-directory: docs
+
   visual-regression-tests:
     runs-on: ubuntu-latest
     needs: [build]

Diff for: .gitignore

@@ -61,9 +61,13 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/source/_static/
-docs/source/_static/embed-bundle.js
-docs/source/_static/embed-bundle.js.map
+docs/_static/
+docs/_static/embed-bundle.js
+docs/_static/embed-bundle.js.map
+docs/build
+docs/output
+docs/jupyter_execute
+
 
 # PyBuilder
 target/
@@ -159,8 +163,13 @@ package-lock.json
 # Packed lab extensions
 ipyopenlayers/labextension
 ipyopenlayers/nbextension
-
 !ipyopenlayers/nbextension/extension.js
 
 
 .yarn
+.vscode/
+
+#jupyter lite
+.jupyterlite.doit.db
+lite_build_output/dist
+lite_build_output/.jupyterlite.doit.db

Diff for: docs/Makefile

@@ -0,0 +1,5 @@
+API Reference
+=============
+
+.. automodule:: ipyopenlayers.openlayers
+   :members:

Diff for: docs/api_reference/index.rst

@@ -0,0 +1,22 @@
+name: ipyopenlayers-docs
+
+channels:
+  - conda-forge
+
+dependencies:
+  - yarn~=3.0
+  - jupyterlab~=4.0
+  - jupyter-packaging~=0.12
+  - sphinx
+  - jupyter-sphinx
+  - nbsphinx
+  - nbsphinx-link
+  - python-build
+  - branca
+  - requests
+  - hatch
+  - pydata-sphinx-theme
+  - jupyterlite-sphinx
+  - jupyterlite-xeus
+  - pip:
+      - ..

Diff for: docs/build-environment.yml

@@ -31,6 +31,7 @@
     'nbsphinx',
     'jupyter_sphinx',
     'nbsphinx_link',
+    'jupyterlite_sphinx',
 ]
 
 # Set the nbsphinx JS path to empty to avoid showing twice of the widgets
@@ -72,7 +73,7 @@
 # get version from python package:
 import os
 here = os.path.dirname(__file__)
-repo = os.path.join(here, '..', '..')
+repo = os.path.join(here, '..')
 _version_py = os.path.join(repo, 'ipyopenlayers', '_version.py')
 version_ns = {}
 with open(_version_py) as f:
@@ -114,7 +115,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 
 # -- Options for HTMLHelp output ------------------------------------------
@@ -181,18 +182,13 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}
 
 # Read The Docs
 # on_rtd is whether we are on readthedocs.org, this line of code grabbed from
 # docs.readthedocs.org
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
 # otherwise, readthedocs.org uses their theme by default, so no need to specify it
 
 
@@ -211,3 +207,11 @@ def add_scripts(app):
                 logger.warning('missing javascript file: %s' % fname)
             app.add_js_file(fname)
     app.connect('builder-inited', add_scripts)
+
+jupyterlite_dir = "."
+jupyterlite_contents = "../examples/"
+jupyterlite_silence = False
+jupyterlite_bind_ipynb_suffix = False
+
+html_theme = "pydata_sphinx_theme"
+htmlhelp_basename = "ipyopenlayersdoc"

Diff for: docs/source/conf.py renamed to docs/conf.py

@@ -0,0 +1,43 @@
+Fullscreen Control
+==================
+
+
+The Fullscreen Control in `ipyopenlayers` allows users to toggle the map view between fullscreen and windowed modes. This control enhances the user experience by providing an easy way to expand the map to occupy the entire screen.
+
+
+Example
+-------
+
+
+.. jupyter-execute::
+
+
+   from ipyopenlayers import Map, FullScreen, RasterTileLayer
+
+
+   # Create a map with initial zoom level and center coordinates
+   m = Map(center=[0, 0], zoom=2)
+
+   # Add layer
+   layer=RasterTileLayer()
+   m.add_layer(layer)
+
+   # Add a FullscreenControl to the map
+   fullscreen_control = FullScreen()
+   m.add_control(fullscreen_control)
+
+
+   # Display the map
+   m
+
+
+
+
+Attributes
+----------
+
+
+.. autoclass:: ipyopenlayers.openlayers.FullScreen
+  :members:
+
+

Diff for: docs/controls/fullscreen_control.rst

@@ -0,0 +1,11 @@
+Controls
+===================
+Controls provide interactive elements on a map that allow users to manipulate the map view or access additional functionalities. These controls can include zoom buttons, layer switches, and other user interface elements that enhance the usability and functionality of the map.
+
+.. toctree::
+   :maxdepth: 1
+
+   zoomslider_control
+   scaleline_control
+   fullscreen_control
+   mouseposition_control

Diff for: docs/controls/index.rst

@@ -0,0 +1,42 @@
+Mouse Position Control
+======================
+
+
+The Mouse Position Control in `ipyopenlayers` shows the geographical coordinates of the mouse pointer on the map. This control is useful for users who need to know the precise location of their cursor within the map view.
+
+
+Example
+-------
+
+
+.. jupyter-execute::
+
+
+   from ipyopenlayers import Map, MousePosition, RasterTileLayer
+
+
+   # Create a map with initial zoom level and center coordinates
+   m = Map(center=[0, 0], zoom=2)
+
+   # Add layer
+   layer=RasterTileLayer()
+   m.add_layer(layer)
+
+
+   # Add a MousePositionControl to the map
+   mouseposition_control = MousePosition()
+   m.add_control(mouseposition_control)
+
+
+   # Display the map
+   m
+
+
+
+
+Attributes
+----------
+
+
+.. autoclass:: ipyopenlayers.openlayers.MousePosition
+  :members:

Diff for: docs/controls/mouseposition_control.rst

@@ -0,0 +1,42 @@
+Scaleline Control
+=================
+
+
+The Scaleline Control in `ipyopenlayers` displays a scale line on the map, providing users with a visual reference for the map's scale. This helps users to understand the distances represented on the map at the current zoom level.
+
+
+Example
+-------
+
+
+.. jupyter-execute::
+
+
+   from ipyopenlayers import Map, ScaleLine, RasterTileLayer
+
+
+   # Create a map with initial zoom level and center coordinates
+   m = Map(center=[0, 0], zoom=2)
+   
+   # Add layer
+   layer=RasterTileLayer()
+   m.add_layer(layer)
+
+
+   # Add a ScalelineControl to the map
+   scaleline_control = ScaleLine()
+   m.add_control(scaleline_control)
+
+
+   # Display the map
+   m
+
+
+
+
+Attributes
+----------
+
+
+.. autoclass:: ipyopenlayers.openlayers.ScaleLine
+  :members:

Diff for: docs/controls/scaleline_control.rst

@@ -0,0 +1,43 @@
+Zoom Slider Control
+===================
+
+
+The Zoom Slider Control in `ipyopenlayers` provides a convenient slider interface for users to control the zoom level of the map.
+This control enhances the user experience by allowing a more intuitive and precise adjustment of the zoom level.
+
+
+Example
+-------
+
+
+.. jupyter-execute::
+
+
+   from ipyopenlayers import Map, ZoomSlider, RasterTileLayer
+
+
+   # Create a map with initial zoom level and center coordinates
+   m = Map(center=[0, 0], zoom=2)
+
+   # Add layer
+   layer=RasterTileLayer()
+   m.add_layer(layer)
+
+
+   # Add a ZoomSlider control to the map
+   zoom_slider = ZoomSlider()
+   m.add_control(zoom_slider)
+
+
+   # Display the map
+   m
+
+
+
+
+Attributes
+----------
+
+
+.. autoclass:: ipyopenlayers.openlayers.ZoomSlider
+  :members:

Diff for: docs/controls/zoomslider_control.rst

@@ -1,11 +1,11 @@
-name: ipyopenlayers_docs
+name: xeus-python-kernel
 channels:
+  - https://repo.mamba.pm/emscripten-forge
   - conda-forge
 dependencies:
-  - python=3.*
-  - nodejs
-  - jupyter_sphinx
-  - sphinx
-  - sphinx_rtd_theme
-  - nbsphinx
-  - nbsphinx-link
+  - python=3.11
+  - xeus-python
+  - ipywidgets
+  - traitlets
+  - pip:
+    - ..