first draft of documentation for JupyterGIS (#195)

* first draft of documentation for JupyterGIS
based on JupyterCAD documentation

* Update docs/source/contributing.rst

Co-authored-by: martinRenou <martin.renou@gmail.com>

---------

Co-authored-by: martinRenou <martin.renou@gmail.com>

docs/environment.yml

@@ -2,7 +2,10 @@ name: jupytergis
 channels:
   - conda-forge
 dependencies:
+  - python=3.12
   - pip
   - sphinx
   - pydata-sphinx-theme
   - sphinx-autodoc-typehints
+  - pip:
+      - jupytergis

docs/source/collab.rst

@@ -0,0 +1,8 @@
+.. _collab:
+
+======================
+Collaborative Features
+======================
+
+One of the standout features of JupyterGIS is its shared editing functionality, which **seamlessly connects users across different interfaces within the JupyterGIS ecosystem**. Whether collaborators are using the JupyterLab GIS extension, or working with the Python API in a Notebook, **any changes made to a shared document are instantly reflected for all users**.
+

docs/source/conf.py

@@ -15,7 +15,7 @@
 source_suffix = ".rst"
 master_doc = "index"
 project = "JupyterGIS"
-copyright = "2023, The JupyterGIS Development Team"
+copyright = "2024, The JupyterGIS Development Team"
 author = "The JupyterGIS Development Team"
 language = "en"
 
@@ -25,4 +25,4 @@
 todo_include_todos = False
 htmlhelp_basename = "jupytergisdoc"
 
-intersphinx_mapping = {"https://docs.python.org": None}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

docs/source/contributing.rst

@@ -0,0 +1,54 @@
+.. _contributing:
+
+============
+Contributing
+============
+
+Development install
+-------------------
+
+**Note:** You will need :ref:`Node.js <https://nodejs.org/>` to build the extension package.
+
+The ``jlpm`` command is JupyterLab's pinned version of
+:ref:`yarn <https://yarnpkg.com/>` that is installed with JupyterLab. You may use
+:ref:`yarn <https://yarnpkg.com/>` or :ref:`npm <https://www.npmjs.com/>` in lieu of ``jlpm`` below.
+
+.. code-block:: bash
+
+    # Clone the repo to your local environment
+    git clone https://github.com/geojupyter/jupytergis.git
+    # Change directory to the jupytergis directory
+    cd jupytergis
+    # Install JupyterLab for jlpm
+    pip install jupyterlab
+    # Install package in development mode
+    python scripts/dev-install.py
+    # Rebuild extension Typescript source after making changes
+    jlpm run build
+
+You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
+
+.. code-block:: bash
+
+    # Watch the source directory in one terminal, automatically rebuilding when needed
+    jlpm run watch
+    # Run JupyterLab in another terminal
+    jupyter lab
+
+With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).
+
+By default, the ``jlpm run build`` command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:
+
+.. code-block:: bash
+
+    jupyter lab build --minimize=False
+
+
+Development uninstall
+----------------------
+
+.. code-block:: bash
+
+    pip uninstall jupytergis
+
+In development mode, you will also need to remove the symlink created by ``jupyter labextension develop`` command. To find its location, you can run ``jupyter labextension list`` to figure out where the ``labextensions`` folder is located. Then you can remove the symlink named ``jupytergis`` within that folder.

docs/source/extension.rst

@@ -0,0 +1,15 @@
+.. _extension:
+
+====================
+JupyterLab Extension
+====================
+
+JupyterGIS comes with a JupyterLab extension that embeds QGIS features directly into the JupyterLab UI.
+This extension allows you to:
+
+* Open ``.qgz`` and ``.jGIS``` files in JupyterLab
+* Create new ``.jGIS`` files
+* Edit those files by adding new vector or raster layers, modifying geometries, and performing spatial operations.
+
+.. image:: assets/lab_ext.webp
+  :alt: JupyterGIS JupyterLab extension

docs/source/index.rst

@@ -1,3 +1,35 @@
 ==========
 JupyterGIS
 ==========
+
+JupyterGIS is a JupyterLab extension for collaborative GIS (Geographical Information System). It is designed to 
+allow multiple people to work on the same geospatial project simultaneously, facilitating discussion and collaboration 
+around map layers, spatial analyses, and other GIS data being developed.
+
+JupyterGIS provides basic support for `QGIS <https://www.qgis.org>`_ project files, allowing users to import and export
+projects seamlessly between QGIS and JupyterLab.
+This compatibility preserves layer styles, data sources, and project settings, enabling smooth transitions between GIS work
+in QGIS and collaborative, cloud-based work in JupyterLab.
+
+Beyond QGIS project support, JupyterGIS offers a range of features tailored specifically for collaborative geospatial analysis. 
+Users can edit, visualize, and analyze spatial data together in real-time, share map layers, and annotate directly within the 
+JupyterLab environment, fostering efficient teamwork on GIS projects. 
+
+Python users can further extend JupyterGIS workflows by integrating with Python geospatial libraries, such as GeoPandas, Xarray 
+and Rasterio, to perform custom analyses and automate processes. Together, these features make JupyterGIS a powerful tool for 
+both collaborative mapping and in-depth geospatial analysis.
+
+.. image:: ../../jupytergis.png
+  :alt: JupyterGIS application
+
+Table of contents
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   install
+   extension
+   python_api
+   collab.rst
+   contributing.rst

docs/source/install.rst

@@ -0,0 +1,17 @@
+.. _install:
+
+=====================
+Installing JupyterGIS
+=====================
+
+JupyterGIS can be installed with ``pip``
+
+.. code-block:: bash
+
+   pip install jupytergis
+
+It is best if you also install ``qgis``, this will allow you to open ``.qgz`` files. It can be installed using ``mamba`` or ``conda``
+
+.. code-block:: bash
+
+   mamba install -c conda-forge qgis

docs/source/python_api.rst

@@ -0,0 +1,44 @@
+.. _python_api:
+
+==========
+Python API
+==========
+
+Basic Usage
+===========
+
+JupyterGIS provides a Python API that can be used for opening QGIS projects,
+add raster or vector layers and apply filtering.
+
+You can open an existing QGIS project and **display it in your Jupyter Notebook**:
+
+.. code-block:: Python
+
+    from jupytergis import GISDocument
+
+    doc = GISDocument('file.qgz')
+
+    doc
+
+**Opening an existing file connects you to the file’s collaborative session**,
+meaning that anyone working on the same QGIS project file, whether through the 
+JupyterLab extension or the Python API, will see the edits you make.
+
+Creating a ``GISDocument`` object without providing a path to an existing file would create a
+new empty document:
+
+.. code-block:: Python
+
+    from jupytergis import GISDocument
+
+    doc = GISDocument()
+
+    doc
+
+Once the document is opened/created, you can start creating GIS layers.
+
+``GISDocument`` API Reference
+=============================
+
+.. autoclass:: jupytergis.GISDocument
+    :members: