geojupyter · martinRenou · Feb 4, 2025 · Feb 3, 2025 · Feb 3, 2025 · Feb 4, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,4 @@
-# JupyterGIS Changelog
+# Changelog
 
 <!-- <START NEW CHANGELOG ENTRY> -->
 

diff --git a/docs/contributor_guide/code_quality.rst b/docs/contributor_guide/code_quality.rst
@@ -0,0 +1,25 @@
+============
+Code quality
+============
+
+We have several tools configured for checking code quality:
+
+* Pre-commit checks run automatically at commit time.
+  Install checks with ``pre-commit install``.
+  Run them manually with ``pre-commit run --all-files``.
+  **Will exit non-zero when finding errors or changing files.**
+
+  * Ruff formats and lints (sometimes autofixes) Python code.
+
+  * Generic pre-commit checks help avoid common mistakes like committing large
+    files or trailing whitespace.
+
+* Package scripts (defined in ``package.json``) to check (and/or fix)
+  TypeScript, JavaScript, CSS, JSON, Markdown, and YAML.
+  Run manually with ``jlpm run lint``.
+  **Will exit 0 when applying fixes.
+  Check the logs and/or ``git status`` after every run.**
+
+  * Prettier formats the file types listed above.
+
+  * Eslint lints (sometimes autofixes) JS/TS code.
diff --git a/docs/contributing.rst → docs/contributor_guide/development_setup.rst b/docs/contributing.rst → docs/contributor_guide/development_setup.rst
@@ -1,9 +1,9 @@
-============
-Contributing
-============
+=================
+Development setup
+=================
 
 Development install
--------------------
+===================
 
 .. note::
 
@@ -15,7 +15,7 @@ Development install
 
 
 Clone the source
-^^^^^^^^^^^^^^^^
+----------------
 
 .. code-block:: bash
 
@@ -27,7 +27,7 @@ Clone the source
 
 
 Create a virtual environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------
 
 .. tabs::
 
@@ -60,7 +60,7 @@ Create a virtual environment
 
 
 Install dependencies and build
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
 
 .. code-block:: bash
 
@@ -84,7 +84,7 @@ Install dependencies and build
 
 
 Watch for changes and rebuild
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------
 
 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.
 
@@ -105,47 +105,10 @@ With the watch command running, every saved change will immediately be built loc
 
 
 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.
-
-
-Code quality
-------------
-
-We have several tools configured for checking code quality:
-
-* Pre-commit checks run automatically at commit time.
-  Install checks with ``pre-commit install``.
-  Run them manually with ``pre-commit run --all-files``.
-  **Will exit non-zero when finding errors or changing files.**
-
-  * Ruff formats and lints (sometimes autofixes) Python code.
-
-  * Generic pre-commit checks help avoid common mistakes like committing large
-    files or trailing whitespace.
-
-* Package scripts (defined in ``package.json``) to check (and/or fix)
-  TypeScript, JavaScript, CSS, JSON, Markdown, and YAML.
-  Run manually with ``jlpm run lint``.
-  **Will exit 0 when applying fixes.
-  Check the logs and/or ``git status`` after every run.**
-
-  * Prettier formats the file types listed above.
-
-  * Eslint lints (sometimes autofixes) JS/TS code.
-
-
-Troubleshooting
----------------
-
-* Setup of development environment hangs indefinitely when running the
-  ``dev-install.py`` step, specifically on the Yarn linking step.
-
-  * This may be caused by having a ``.gitignore`` file in your home directory.
-    This is a `known issue with Nx <https://github.com/nrwl/nx/issues/27494>`_.
-    The `only known workaround <https://github.com/nrwl/nx/issues/27494#issuecomment-2481207598>`_ is to remove the ``.gitignore`` file from your home directory or to work in a location outside of the home directory tree.
diff --git a/docs/contributor_guide/index.md b/docs/contributor_guide/index.md
@@ -0,0 +1,15 @@
+# Contributor guide
+
+We're thrilled you're ready to contribute to JupyterGIS!
+
+To chat with other contributors, please
+[join us on Zulip](https://jupyter.zulipchat.com/#narrow/channel/471314-geojupyter)!
+
+```{toctree}
+:maxdepth: 2
+
+development_setup
+code_quality
+releasing
+troubleshooting
+```
diff --git a/docs/contributor_guide/releasing.md b/docs/contributor_guide/releasing.md
@@ -0,0 +1,61 @@
+# Releasing
+
+## Automated Releases with `jupyter_releaser`
+
+The recommended way to make a release is to use
+[`jupyter_releaser`](https://jupyter-releaser.readthedocs.io/en/latest/get_started/making_release_from_repo.html)
+in GitHub Actions.
+Follow the linked instructions.
+
+**This project uses [Semantic Versioning](https://semver.org)**.
+
+:::{important}
+Because this project is in early development, we **do not bump the major version number**.
+Most changes are minor version bumps, even breaking changes.
+See [the SemVer FAQ](https://semver.org/#how-should-i-deal-with-revisions-in-the-0yz-initial-development-phase) for more.
+:::
+
+### Specifying a version spec
+
+When prompted for a "New Version Specifier", the default value is `next`.
+This will bump the packages as follows:
+
+- `0.1.0a0` -> `0.1.0a1`
+- `0.1.0b7` -> `0.1.0b8`
+- `0.1.0` -> `0.1.1`
+
+This is often **not** what we want.
+To bump to another version, you can specify the Python version directly.
+For example:
+
+- `0.1.0b8`
+- `0.4.0`
+- `1.0.0`
+- `1.2.0rc0`
+
+You can also specify a version part, e.g.:
+
+- `patch`
+  - Would bump `0.3.0` -> `0.3.1`
+- `minor`
+  - Would bump `0.3.0` -> `0.4.0`
+- `major`
+  - Would bump `0.3.0` -> `1.0.0`
+
+## Release assets
+
+JupyterGIS is published to:
+
+- PyPI:
+  - <https://pypi.org/project/jupytergis/>: A metapackage.
+- Conda Forge
+  - <https://github.com/conda-forge/jupytergis-packages-feedstock>
+- npm:
+  - <https://www.npmjs.com/package/@jupytergis/base>
+  - <https://www.npmjs.com/package/@jupytergis/schema>
+  - <https://www.npmjs.com/package/@jupytergis/jupytergis-core>
+  - <https://www.npmjs.com/package/@jupytergis/jupytergis-lab>
+  - <https://www.npmjs.com/package/@jupytergis/jupytergis-qgis>
+
+Release assets are also available on GitHub. For example for
+[`0.3.0`](https://github.com/geojupyter/jupytergis/releases/tag/v0.3.0):
diff --git a/docs/contributor_guide/troubleshooting.rst b/docs/contributor_guide/troubleshooting.rst
@@ -0,0 +1,10 @@
+===============
+Troubleshooting
+===============
+
+* Setup of development environment hangs indefinitely when running the
+  ``dev-install.py`` step, specifically on the Yarn linking step.
+
+  * This may be caused by having a ``.gitignore`` file in your home directory.
+    This is a `known issue with Nx <https://github.com/nrwl/nx/issues/27494>`_.
+    The `only known workaround <https://github.com/nrwl/nx/issues/27494#issuecomment-2481207598>`_ is to remove the ``.gitignore`` file from your home directory or to work in a location outside of the home directory tree.
diff --git a/docs/index.rst b/docs/index.rst
@@ -26,16 +26,33 @@ both collaborative mapping and in-depth geospatial analysis.
 .. image:: ../jupytergis.png
   :alt: JupyterGIS application
 
-Table of contents
+
+User guide
+==========
+
+Information about using JupyterGIS.
+
+.. toctree::
+   :maxdepth: 2
+
+   user_guide/index
+
+
+Contributor guide
 =================
 
+Information about contributing to the JupyterGIS project.
+
+.. toctree::
+   :maxdepth: 2
+
+   contributor_guide/index
+
+
+More
+====
+
 .. toctree::
    :maxdepth: 2
 
-   install
-   extension
-   python_api
-   collab.rst
-   tutorials/intro.md
-   contributing.rst
-   changelog.rst
+   changelog
diff --git a/docs/collab.rst → docs/user_guide/features/collab.rst b/docs/collab.rst → docs/user_guide/features/collab.rst
diff --git a/docs/extension.rst → docs/user_guide/features/extension.rst b/docs/extension.rst → docs/user_guide/features/extension.rst
@@ -11,5 +11,5 @@ This extension allows you to:
 * 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
+.. image:: ../../assets/lab_ext.webp
   :alt: JupyterGIS JupyterLab extension
diff --git a/docs/user_guide/features/index.md b/docs/user_guide/features/index.md
@@ -0,0 +1,8 @@
+# Features
+
+```{toctree}
+:maxdepth:
+
+extension.rst
+collab.rst
+```
diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
@@ -0,0 +1,23 @@
+# User guide
+
+Thanks for trying out JupyterGIS!
+
+```{cssclass} try-in-jupyterlite-button
+
+[Try it with JupyterLite!](lite/)
+```
+
+JupyterGIS offers:
+
+- **Collaborative GIS Environment**: Work together on geographic data projects in real-time.
+- **QGIS File Support**: Load, visualize, and manipulate QGIS project files (`.qgs`, `.qgz`), and other GIS data formats.
+- **Interactive Maps**: Render interactive maps and geospatial visualizations within Jupyter notebooks using the JupyterGIS Python API.
+
+```{toctree}
+:maxdepth: 2
+
+install
+tutorials/index
+features/index
+python_api
+```
diff --git a/docs/install.rst → docs/user_guide/install.rst b/docs/install.rst → docs/user_guide/install.rst
diff --git a/docs/python_api.rst → docs/user_guide/python_api.rst b/docs/python_api.rst → docs/user_guide/python_api.rst
diff --git a/docs/user_guide/tutorials/index.md b/docs/user_guide/tutorials/index.md
@@ -0,0 +1,8 @@
+# Tutorials
+
+```{toctree}
+:maxdepth: 2
+:glob:
+
+*
+```