README cosmetics (#10)

Signed-off-by: Emmanuel Decitre <[email protected]>

README.md

@@ -1,6 +1,6 @@
 [![Python package](https://github.com/heremaps/here-search-demo/actions/workflows/test.yml/badge.svg)](https://github.com/heremaps/here-search-demo/actions/workflows/test.yml)
 [![codecov](https://codecov.io/gh/heremaps/here-search-demo/branch/main/graph/badge.svg?token=MVFCS4BUFN)](https://codecov.io/gh/heremaps/here-search-demo)
-[![lite-badge](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://decitre.github.io/here-search-demo-updated/lab/?path=demo.ipynb)
+[![lite-badge](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)][3]
 
 
 # HERE Search notebooks
@@ -36,7 +36,7 @@ Use the `here-search-notebooks` script with your HERE API Key:
    API_KEY="your API key" here-search-notebooks
    ```
 
-(More [details][2])
+(Additional [notes][2])
 
 ## License
 
@@ -46,6 +46,6 @@ This project is licensed under the MIT license - see the [LICENSE](./LICENSE) fi
 
 [1]: https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/quick-start.html#get-an-api-key
 [2]: https://github.com/heremaps/here-search-demo/blob/main/docs/developers.md
-[3]: https://decitre.github.io/here-search-demo-updated/lab/?path=demo.ipynb
+[3]: https://heremaps.github.io/here-search-demo/lab/?path=demo.ipynb
 [4]: https://developer.here.com/documentation/geocoding-search-api/dev_guide/index.html
 [5]: https://www.here.com/get-started/pricing

docs/developers.md

@@ -2,42 +2,47 @@
 
 ### Setup a Notebook Python environment
 
-It is recommended to use a Python virtual environment. The below recipe uses the python batteries `venv` module.
-
-1. Virtual environment
+It is recommended to use a Python virtual environment. In that environment, after a `pip install -e '.[lab]'`, 
+you will need to install a kernel. For instance with a:
 
    ```
-   mkdir -p ~/virtualenv; (cd ~/virtualenv; python -m venv search-notebook)
-   source ~/virtualenv/search-notebook/bin/activate
+   python -m ipykernel install \
+      --prefix $(python -c "import sys; print(sys.prefix)") \
+      --name search_demo --display-name "search demo"
    ```
+
+To run the notebook on Jupyter Classic, you will need:
 
-2. Download and install
-
-   For users:
 
    ```
-   pip -v install here-search-demo
+   jupyter nbextension enable --py widgetsnbextension
+   jupyter labextension install @jupyterlab/geojson-extension
    ```
 
-   For contributors/developers:
+### Versioning
 
-   ```
-   git clone [email protected]:heremaps/here-search-demo.git
-   cd search-notebook-ext
-   pip install -e .
-   ```
+To update the package version, use `bumpver`. For instance:
 
-3. Jupyter config
-
-   ```
-   python -m ipykernel install --user --name search_demo --display-name "search demo"
    ```
+   bumpver update --patch --dry 
    
-To run the notebook on Jupyter Classic, you will need:
-
-   ```
-   jupyter nbextension enable --py widgetsnbextension
-   jupyter labextension install @jupyterlab/geojson-extension
+   INFO    - fetching tags from remote (to turn off use: -n / --no-fetch)
+   INFO    - Latest version from VCS tag: 0.9.0
+   INFO    - Working dir version        : 0.9.0
+   INFO    - Old Version: 0.9.0
+   INFO    - New Version: 0.9.1
+   --- docs/developers.md
+   +++ docs/developers.md
+   @@ -56,7 +56,7 @@
+       ```
+       try:
+          import piplite
+   -      await piplite.install(["ipywidgets==8.1.0", "ipyleaflet==0.17.3", "emfs:here_search_demo-0.9.0-py3-none-any.whl"], keep_going=True)
+   +      await piplite.install(["ipywidgets==8.1.0", "ipyleaflet==0.17.3", "emfs:here_search_demo-0.9.1-py3-none-any.whl"], keep_going=True)
+       except ImportError:
+          pass
+       ```
+   (...)
    ```
 
 ### Test on MacOS / python3.7
@@ -61,11 +66,11 @@ To run the notebook on Jupyter Classic, you will need:
 
 ### JupyterLite
 
-[JupyterLite](https://jupyterlite.readthedocs.io/en/latest/) is a JupyterLab distribution that runs entirely in the browser.
+[JupyterLite](https://JupyterLite.readthedocs.io/en/latest/) is a JupyterLab distribution that runs entirely in the browser.
 The Python kernels are backed by [`Pyodide`](https://pyodide.org/en/stable/) running in a Web Worker.
 
 Pyodide can not be used outside a browser. But for development purposes (type hints), it is advised to
-install its [`py`](https://github.com/pyodide/pyodide/tree/main/src/py) package into the venv used for `search-notebook-ext`
+install its [`py`](https://github.com/pyodide/pyodide/tree/main/src/py) package into the venv used for `here-search-demo`.
 
    ```
    git clone [email protected]:pyodide/pyodide.git
@@ -78,37 +83,54 @@ For the Pyodide kernels to be able to use certain packages, those need to be ins
    ```
    try:
       import piplite
-      await piplite.install(["ipywidgets==7.7.1", "ipyleaflet==0.17.1", "emfs:here_search_widget-0.8.1-py3-none-any.whl"], keep_going=True)
+      await piplite.install(["ipywidgets==8.1.0", "ipyleaflet==0.17.3", "emfs:here_search_demo-0.9.0-py3-none-any.whl"], keep_going=True)
    except ImportError:
       pass
    ```
 
-The version of `here_search_widget` in the `.ipynb` files is updated through `bumpver`.
+The version of `here_search_demo` in the `.ipynb` files and this `developers.md` is updated through `bumpver`.
 
 #### From a local git clone
 
-To test the jupyterlite page locally, run from the local git repository:
+To test the JupyterLite page locally, run from the local git repository:
 
    ```
-   $(find . -name "lite_run.sh")
+   $(find . -name "lite-run.sh")
    ```
 
 Option `-n` only builds the page and does not serve it. 
 
-A way to get the sources without git cloning the project is to use the source distribution:
+#### Without git clone
+
+To test the JupyterLite page locally, run in a virtualenv :
 
    ```
-   pip install --upgrade pip
    pip download here-search-demo --no-deps --no-binary ":all:"
    
    tar xpfz $(find . -name "*.tar.gz")
    
-   $(find . -name "lite_run.sh")
+   $(find . -name "lite-run.sh")
    ```
 
-## Inject a lat/lon using geojs.io
+#### Clear your browser cache
+
+By default, JupyterLite uses the [browser storage][1] to store settings and site preferences. 
+It is sometimes helpful to clear in the browser settings the `127.0.0.1` site data to not use a stale state. 
+
+
+### Inject a lat/lon using geojs.io
+
+
+`here-search-demo` facilitates the use of the services from [geojs.io][2] to discover the location behind an IP address.
+The `get_lat_lon` helper is not used in the demo widgets. If you need to inject the geolocation associated with 
+your IP, please check the [GeoJS Terms Of Service][3].
+
 
    ```
    from here_search.demo.util import get_lat_lon
    latitude, longitude = await get_lat_lon()
    ```
+
+[1]: https://jupyterlite.readthedocs.io/en/latest/howto/configure/storage.html
+[2]: https://www.geojs.io/
+[3]: https://www.geojs.io/tos/

pyproject.toml

@@ -23,4 +23,6 @@ push = true
 "src/here_search/demo/notebooks/*.ipynb" = [
     'here_search_demo-{version}-py3-none-any.whl'
 ]
-
+"docs/developers.md" = [
+    'here_search_demo-{version}-py3-none-any.whl'
+]