Merge pull request #98 from NERDSITU/97-update-installation-instructions

Doc: Migrate Installation instructions to `conda-forge` and modify doc landing page

CONTRIBUTING.md

@@ -165,7 +165,7 @@ as [GitHub issues](https://github.com/NERDSITU/superblockify/issues).
 
 If you prefer to directly put your enhancement into code, you are welcome to submit a
 pull request.
-When doing so, we reccomend to set up your development environment with the
+When doing so, we recommend setting up your development environment with the
 development dependencies and an editable installation of the package, like so:
 
 ```bash

README.md

@@ -35,10 +35,13 @@ or [`micromamba`](https://mamba.readthedocs.io/en/latest/installation/micromamba
 to create the virtual environment `sb_env`:
 
 ```bash
-conda create -n sb_env -c conda-forge python=3.12 osmnx=1.9.2
+conda create -n sb_env -c conda-forge superblockify
+conda activate sb_env
 ```
 
-> **Note:** While `pip` can install OSMnx, it's not officially supported due to potential issues with C dependencies. If unsure, use `conda` as instructed above to avoid problems. 
+> **Note:** While `pip` can install `superblockify`, it's not officially supported due
+> to potential issues with C dependencies needed for OSMnx.
+> If unsure, use `conda` as instructed above to avoid problems.
 
 *Alternatively*, or if you run into
 issues, [clone this repository](https://github.com/NERDSITU/superblockify/archive/refs/heads/main.zip)
@@ -48,13 +51,6 @@ file:
 
 ```bash
 conda env create --file environment.yml
-```
-
-### Install package
-
-Next, activate the environment and install the package:
-
-```bash
 conda activate sb_env
 pip install superblockify
 ```
@@ -98,9 +94,10 @@ see [`.github/workflows/test.yml`](https://github.com/NERDSITU/superblockify/blo
 
 ## Credits & Funding
 
-* Carlson M. Büth (Implementation)
-* Anastassia Vybornova (Supervision)
-* Michael Szell (Concept)
+* Carlson M. Büth, [@cbueth](https://github.com/cbueth) (Implementation)
+* Anastassia Vybornova, [@anastassiavybornova](https://github.com/anastassiavybornova)
+  (Supervision)
+* Michael Szell, [@mszell](https://github.com/mszell) (Concept)
 
 Funded by the European
 Union, [EU Horizon grant JUST STREETS](https://cordis.europa.eu/project/id/101104240)

docs/index.rst

@@ -4,9 +4,34 @@
   :width: 1121
   :alt: superblockify logo
 
-***************************
-superblockify documentation
-***************************
+.. raw:: html
+
+   <div style="height: 10px;"></div>
+
+.. |spacer| raw:: html
+
+   <div style="width: 10px; display: inline-block;"></div>
+
+.. list-table::
+   :widths: auto
+   :header-rows: 0
+   :align: center
+
+   * - .. image:: https://joss.theoj.org/papers/10.21105/joss.06798/status.svg
+         :target: https://doi.org/10.21105/joss.06798
+         :alt: JOSS status
+     - |spacer|
+     - .. image:: https://img.shields.io/conda/vn/conda-forge/superblockify.svg
+         :target: https://anaconda.org/conda-forge/superblockify
+         :alt: Conda version
+     - |spacer|
+     - .. image:: https://img.shields.io/pypi/pyversions/superblockify
+         :target: https://pypi.org/project/superblockify/
+         :alt: Python version
+     - |spacer|
+     - .. image:: https://img.shields.io/pypi/l/superblockify
+         :target: https://pypi.org/project/superblockify/
+         :alt: License
 
 On these pages you can find documentation for superblockify.
 
@@ -41,6 +66,13 @@ With the advent of new computational tools and datasets, there is an opportunity
 
 The target audience for `superblockify` includes urban planners, researchers in urban studies, data scientists interested in urban data, and policymakers involved in urban development. By providing a tool for Superblock analysis, `superblockify` aims to support these professionals in their work towards creating safer, quieter, and more environmentally friendly urban environments.
 
+How to cite
+===========
+If you use `superblockify` in your research, please cite the
+JOSS paper `doi:10.21105/joss.06798 <https://doi.org/10.21105/joss.06798>`__, e.g.:
+
+    Büth et al., (2024). superblockify: A Python Package for Automated Generation, Visualization, and Analysis of Potential Superblocks in Cities. Journal of Open Source Software, 9(100), 6798, https://doi.org/10.21105/joss.06798
+
 Contributing
 ============
 If you want to contribute to the development of superblockify, please read the

docs/installation.md

@@ -8,24 +8,22 @@ or [`micromamba`](https://mamba.readthedocs.io/en/latest/installation/micromamba
 to create the virtual environment `sb_env`:
 
 ```bash
-conda create -n sb_env -c conda-forge python=3.12 osmnx=1.9.2
+conda create -n sb_env -c conda-forge superblockify
+conda activate sb_env
 ```
 
-> **Note:** While `pip` can install OSMnx, it's not officially supported due to potential issues with C dependencies. If unsure, use `conda` as instructed above to avoid problems.
+> **Note:** While `pip` can install `superblockify`, it's not officially supported due
+> to potential issues with C dependencies needed for OSMnx. If unsure, use `conda` as
+> instructed above to avoid problems.
 
-*Alternatively*, or if you run into issues, [clone this repository](https://github.com/NERDSITU/superblockify/archive/refs/heads/main.zip) and create the environment via
+*Alternatively*, or if you run into
+issues, [clone this repository](https://github.com/NERDSITU/superblockify/archive/refs/heads/main.zip)
+and create the environment via
 the [`environment.yml`](https://github.com/NERDSITU/superblockify/blob/main/environment.yml)
 file:
 
 ```bash
 conda env create --file environment.yml
-```
-
-### Install package
-
-Next, activate the environment and install the package:
-
-```bash
 conda activate sb_env
 pip install superblockify
 ```
@@ -42,5 +40,4 @@ python -m ipykernel install --user --name=sb_env
 This allows you to run Jupyter with the kernel `sb_env` (Kernel > Change Kernel >
 sb_env)
 
-
 For a guided start after installation, see the following [Usage section](#usage).