Add documentation and tests

.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]

.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

docs/api_reference/index.rst

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

docs/build-environment.yml

@@ -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:
+      - ..

docs/source/conf.py → docs/conf.py

@@ -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"

docs/controls/fullscreen_control.rst

@@ -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:
+
+

docs/controls/index.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

docs/controls/mouseposition_control.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:

docs/controls/scaleline_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:

docs/controls/zoomslider_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:

docs/environment.yml

@@ -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:
+    - ..