Polishdocs w22

.github/workflows/docs.yml

@@ -41,14 +41,6 @@ jobs:
       run:
         shell: bash -el {0}
     steps:
-      - name: Check if GHSL site is under maintenance
-        run: |
-          content=$(curl -s https://jeodpp.jrc.ec.europa.eu/ftp/jrc-opendata/GHSL/)
-          if echo "$content" | grep -q "Under Maintenance"; then
-            echo "GHSL site is under maintenance. Exiting."
-            exit 1
-          fi
-
       - name: Check out Git repository
         uses: actions/checkout@v6
 
@@ -66,10 +58,10 @@ jobs:
       - name: Add Notebook Kernel
         run: python -m ipykernel install --user --name growbikenet --display-name "Python (growbikenet)"
 
-      - name: Generating .rst files
-        run: sphinx-apidoc -o docs/api/ growbikenet/
+      # - name: Generating .rst files
+      #   run: sphinx-apidoc -o docs/api/ growbikenet/
       - name: Generating html
-        run: sphinx-build docs public -b dirhtml
+        run: sphinx-build docs/source/ public -b dirhtml
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

README.md

@@ -49,6 +49,6 @@ Find more information in our docs: [https://bikenetkit.github.io/GrowBikeNet/](h
 ## Supported by
 Development of BikeNetKit/GrowBikeNet was supported by the Innovation Fund Denmark and the EU HORIZON grant JUST STREETS.
 
-[![Innovation Fund Denmark](https://raw.githubusercontent.com/BikeNetKit/GrowBikeNet/refs/heads/main/docs/_static/logo_innovationfund.png)](https://innovationsfonden.dk/en)    [![European Union](https://raw.githubusercontent.com/BikeNetKit/GrowBikeNet/refs/heads/main/docs/_static/logo_eu.png)](https://commission.europa.eu/index_en)   [![JUST STREETS](https://raw.githubusercontent.com/BikeNetKit/GrowBikeNet/refs/heads/main/docs/_static/logo_juststreets.png)](https://www.just-streets.eu/) 
+[![Innovation Fund Denmark](https://raw.githubusercontent.com/BikeNetKit/GrowBikeNet/refs/heads/main/docs/source/_static/logo_innovationfund.png)](https://innovationsfonden.dk/en)    [![European Union](https://raw.githubusercontent.com/BikeNetKit/GrowBikeNet/refs/heads/main/docs/source/_static/logo_eu.png)](https://commission.europa.eu/index_en)   [![JUST STREETS](https://raw.githubusercontent.com/BikeNetKit/GrowBikeNet/refs/heads/main/docs/source/_static/logo_juststreets.png)](https://www.just-streets.eu/) 
 
 

docs/Makefile

@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
+SOURCEDIR     = source
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".

docs/make.bat

@@ -7,7 +7,7 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=.
+set SOURCEDIR=source
 set BUILDDIR=_build
 
 %SPHINXBUILD% >NUL 2>NUL

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

@@ -15,13 +15,16 @@
 
 import os  # noqa
 import sys  # noqa
+from pathlib import Path  # noqa
+from tomllib import load as toml_load  # noqa
 
 sys.path.insert(0, os.path.abspath(".."))
 import growbikenet  # noqa
 
-# version = growbikenet.__version__
-version = "0.8.0"
-release = version
+# dynamically load version
+with Path("../../pyproject.toml").open("rb") as f:
+    pyproject = toml_load(f)
+version = release = pyproject["project"]["version"]
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -55,25 +58,54 @@
 html_static_path = ["_static"]
 
 ### select html theme
-# html_theme = 'alabaster'
 html_theme = "furo"
 
 html_theme_options = {
-    "github_url": "https://github.com/BikeNetKit/GrowBikeNet",
-    "twitter_url": "notwitter.com",
     "pygment_light_style": "tango",
     "logo": {
         "image_light": "logo.png",
         "image_dark": "logo.png",
     },
+    "light_css_variables": {
+        "color-brand-primary": "#096a51",
+        "color-brand-content": "#096a51",
+        "color-brand-visited": "#5b8b75",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#3cd71d",
+        "color-brand-content": "#3cd71d",
+        "color-brand-visited": "#5b8b75",
+    },
+    "footer_icons": [
+        {
+            "name": "Bluesky",
+            "url": "https://bsky.app/profile/bikenetkit.bsky.social",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 18 16">
+                    <path fill-rule="evenodd" transform="scale(0.03018)" d="m135.72 44.03c66.496 49.921 138.02 151.14 164.28 205.46 26.262-54.316 97.782-155.54 164.28-205.46 47.98-36.021 125.72-63.892 125.72 24.795 0 17.712-10.155 148.79-16.111 170.07-20.703 73.984-96.144 92.854-163.25 81.433 117.3 19.964 147.14 86.092 82.697 152.22-122.39 125.59-175.91-31.511-189.63-71.766-2.514-7.3797-3.6904-10.832-3.7077-7.8964-0.0174-2.9357-1.1937 0.51669-3.7077 7.8964-13.714 40.255-67.233 197.36-189.63 71.766-64.444-66.128-34.605-132.26 82.697-152.22-67.108 11.421-142.55-7.4491-163.25-81.433-5.9562-21.282-16.111-152.36-16.111-170.07 0-88.687 77.742-60.816 125.72-24.795z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+        {
+            "name": "GitHub",
+            "url": "https://github.com/BikeNetKit/GrowBikeNet",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
 }
 
 # Generate the API documentation when building
 autosummary_generate = True
 autosummary_imported_members = True
-numpydoc_show_class_members = True
-class_members_toctree = True
-numpydoc_show_inherited_class_members = True
+numpydoc_show_class_members = False
+class_members_toctree = False
+numpydoc_show_inherited_class_members = False
 numpydoc_class_members_toctree = False
 numpydoc_use_plots = True
 autodoc_typehints = "none"
@@ -90,9 +122,8 @@
     .. note::
 
         | This page was generated from `{{ docname }}`__.
-        | Interactive online version: :raw-html:`<a href="https://mybinder.org/GrowBikeNet/master?urlpath=lab/tree/docs/{{ docname }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>`
 
-        __ https://github.com/BikeNetKit/GrowBikeNet/blob/master/docs/{{ docname }}
+        __ https://github.com/BikeNetKit/GrowBikeNet/blob/main/docs/source/{{ docname }}
 """  # noqa: E501
 
 

docs/usage/quickstart.rst → docs/source/getting_started.rst

@@ -1,8 +1,25 @@
-==========
-Quickstart
-==========
+Getting started
+===============
 
-GrowBikeNet takes one mandatory parameter, the city name, which it passes via `OSMnx <https://osmnx.readthedocs.io/>`__ to `Nominatim <https://nominatim.openstreetmap.org/>`__, to download a city's street network. GrowBikeNet then runs the following operations:
+Get Started in 4 Steps
+----------------------
+
+1. Install GrowBikeNet by following the :doc:`installation` guide.
+
+2. Read the :ref:`introducing-growbikenet` section below.
+
+3. Run the :doc:`mwe`.
+
+4. Consult the :doc:`reference_user` for complete details on using the package.
+
+Finally, if you're not already familiar with `NetworkX`_ and `GeoPandas`_, make sure you read their user guides as GrowBikeNet uses their data structures.
+
+.. _introducing-growbikenet:
+
+Introducing GrowBikeNet
+-----------------------
+
+GrowBikeNet is built on top of `OSMnx`_/`NetworkX`_ and `GeoPandas`_. It takes one mandatory parameter, the city name, which it passes via `Nominatim`_ to `OSMnx`_, to download a city's street network. GrowBikeNet then runs the following operations:
 
 * Optional, also download the city's existing bicycle network.
 * Create seed points following :cite:t:`szell2022gub`. By default this is a grid, but it can also be set to the city's rail stations. If the city's existing bicycle network is used, the seed points are first selected on the bicycle network following :cite:t:`folco2023dmn`.
@@ -16,9 +33,15 @@ GrowBikeNet takes one mandatory parameter, the city name, which it passes via `O
 * Optional, a video is generated in the results folder, using the plots as frames.
 
 
-Quickstart contents
--------------------
+To try it out, run the:
+
 .. toctree::
    :maxdepth: 1
 
-   Minimum working example <mwe>
+   Minimum working example <mwe>
+
+
+.. _GeoPandas: https://geopandas.org
+.. _NetworkX: https://networkx.org
+.. _OSMnx: https://osmnx.readthedocs.io
+.. _Nominatim: https://nominatim.openstreetmap.org

docs/index.rst → docs/source/index.rst

@@ -3,11 +3,10 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-===================================
 GrowBikeNet |version| documentation
 ===================================
 
-The Python package `growbikenet` grows an urban bicycle network from scratch or from an existing bicycle network. It is part of `BikeNetKit <https://bikenetkit.org>`__.
+The Python package ``growbikenet`` grows an urban bicycle network from scratch or from an existing bicycle network. It is hosted on `Github <https://github.com/BikeNetKit/GrowBikeNet>`__, part of `BikeNetKit <https://bikenetkit.org>`__.
 
 The software downloads and pre-processes data from OpenStreetMap,
 prepares seed points to connect, runs simulations, saves the results,
@@ -19,34 +18,33 @@ paper <https://github.com/pietrofolco/Data-driven_bicycle_network_planning_for_d
 
 
 Setup and use
-=============
+-------------
 
-To set up GrowBikeNet, see the `Installation <usage/installation>`__ page.
-To use GrowBikeNet, the `Quickstart <usage/quickstart>`__ page
-is a good place to start.
-More on the details of the inner workings can be found on
-the `Reference pages <references>`__.
-Furthermore, you can also find the `API documentation <api>`__.
+To set up GrowBikeNet, see the :doc:`installation` page.
+To use GrowBikeNet, the :doc:`getting_started` page
+is a good place to start, which also explains how the package works in detail. For technical documentation, consult the :doc:`reference_user`.
 
 .. Statement of need
 .. =================
 
 .. TBA
 
 How to cite
-===========
-If you use `growbikenet` in your research, please cite the paper `doi:10.1038/s41598-022-10783-y <https://doi.org/10.1038/s41598-022-10783-y>`__:
+-----------
+
+If you use GrowBikeNet in your research, please cite `the paper <https://doi.org/10.1038/s41598-022-10783-y>`__:
 
     M. Szell, S. Mimar, T. Perlman, G. Ghoshal, R. Sinatra. Growing urban bicycle networks. Scientific Reports 12, 6765 (2022). https://doi.org/10.1038/s41598-022-10783-y
 
 Contributing
-============
+------------
+
 If you want to contribute to the development of GrowBikeNet, please read the
 `CONTRIBUTING.md <https://github.com/BikeNetKit/GrowBikeNet?tab=contributing-ov-file#contributing-to-bikenetkit>`__
 file.
 
 Supported by
-============
+------------
 
 Development of BikeNetKit/GrowBikeNet was supported by the Innovation Fund Denmark
 and the EU HORIZON grant JUST STREETS.
@@ -62,12 +60,14 @@ and the EU HORIZON grant JUST STREETS.
 
 
 Documentation contents
-======================
+----------------------
+
 .. toctree::
    :maxdepth: 1
 
    Home <self>
-   usage/installation
-   usage/quickstart
-   API reference <api>
+   installation
+   getting_started
+   reference_user
+   reference_developer
    references

docs/usage/installation.rst → docs/source/installation.rst

@@ -137,7 +137,7 @@ gbnenv)
 
 
 Development installation
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you want to develop the project, `clone this
 repository <https://github.com/BikeNetKit/growbikenet/archive/refs/heads/main.zip>`__
@@ -148,6 +148,6 @@ and create the environment via the
 
    pixi init --import environment-dev.yml
 
-The developemt environment is called ``gbnenvdev``. Make sure to also
+The development environment is called ``gbnenvdev``. Make sure to also
 read `our contribution
 guidelines <https://github.com/BikeNetKit/GrowBikeNet?tab=contributing-ov-file#contributing-to-bikenetkit>`__.