diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..d21afa0 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,74 @@ +name: Docs + +on: + push: + branches: + - main + paths: + - "bikenetlib/**" + - "docs/**" + - "logging.cfg" + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + generate-deploy-docs: + strategy: + matrix: + python-version: ["3.12"] + os: [ubuntu-latest] + name: Generate documentation + runs-on: ${{ matrix.os }} + env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true + environment: + name: Deploy to github pages + url: ${{ steps.deployment.outputs.page_url }} + defaults: + run: + shell: bash -el {0} + steps: + - name: Check out Git repository + uses: actions/checkout@v7 + + - name: Get week number + run: echo "WEEK=$(date +'%V')" >> $GITHUB_ENV + + - name: Set up Python ${{ matrix.python-version }} + uses: mamba-org/setup-micromamba@v3 + with: + create-args: python=${{ matrix.python-version }} + environment-file: environment-dev.yml + cache-environment: true + cache-environment-key: W${{ env.WEEK }} + + - name: Add Notebook Kernel + run: python -m ipykernel install --user --name bikenetlib --display-name "Python (bikenetlib)" + + # - name: Generating .rst files + # run: sphinx-apidoc -o docs/api/ bikenetlib/ + - name: Generating html + run: sphinx-build docs/source/ public -b dirhtml + + - name: Setup Pages + uses: actions/configure-pages@v6 + - name: Upload artifact + uses: actions/upload-pages-artifact@v5 + with: + # Upload generated html + path: "public/" + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 diff --git a/.gitignore b/.gitignore index a8b0c5d..c8ad1df 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,11 @@ data/ results/ cache/ - +examples/*.gpkg +/*gpkg +docs/source/*.gpkg +docs/source/executed_notebooks/ +docs/jupyter_execute/ # Created by https://www.toptal.com/developers/gitignore/api/visualstudiocode,python,macos,windows # Edit at https://www.toptal.com/developers/gitignore?templates=visualstudiocode,python,macos,windows diff --git a/README.md b/README.md index 2e01599..8e7262b 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ [![Conda Version](https://img.shields.io/conda/vn/conda-forge/bikenetlib?color=10d249)](https://anaconda.org/conda-forge/bikenetlib) [![PyPI Version](https://img.shields.io/pypi/v/bikenetlib?color=10d249)](https://pypi.org/project/BikeNetLib/) +[![Docs](https://github.com/BikeNetKit/BikeNetLib/actions/workflows/docs.yml/badge.svg)](https://docs.bikenetkit.org/BikeNetLib/) [![Test](https://github.com/BikeNetKit/BikeNetLib/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/BikeNetKit/BikeNetLib/actions/workflows/test.yml) [![Code coverage](https://codecov.io/gh/BikeNetKit/BikeNetLib/graph/badge.svg)](https://codecov.io/gh/BikeNetKit/BikeNetLib) [![Mastodon Follow](https://img.shields.io/mastodon/follow/116693348622375119?domain=https%3A%2F%2Ffosstodon.org)](https://fosstodon.org/@BikeNetKit) @@ -15,9 +16,9 @@ in the [BikeNetKit family](https://github.com/BikeNetKit), like [GrowBikeNet](ht BikeNetLib is imported as `bnl`. There are several building blocks: - `bnl.io` – Input and output +- `bnl.osm` – OpenStreetMap constants - `bnl.utils` – Utilities - `bnl.viz` – Visualization -- `bnl.osm` – OpenStreetMap constants BikeNetLib mainly builds on [OSMnx](https://github.com/gboeing/osmnx) and [GeoPandas](https://github.com/geopandas/geopandas). @@ -27,12 +28,18 @@ The recommended way to install BikeNetLib is using [`conda`](https://docs.conda. ``` conda install bikenetlib ``` +### Advanced and development installations +For more installation options, see our [Installation docs](https://docs.bikenetkit.org/BikeNetLib/installation/). ## Usage -In development. +We provide a minimum working example: + +- Jupyter notebook ([examples/mwe.ipynb](examples/mwe.ipynb)) + +For a walkthrough with illustrative examples, see our [Usage docs](https://docs.bikenetkit.org/BikeNetLib/usage/). -## Docs -In development. +## Documentation +Find more information in our docs: [https://docs.bikenetkit.org/BikeNetLib/](https://docs.bikenetkit.org/BikeNetLib/) ## Supported by Development of BikeNetKit/BikeNetLib is supported by the [Innovation Fund Denmark](https://innovationsfonden.dk/en) and the EU HORIZON project [JUST STREETS](https://www.just-streets.eu). diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..92dd33a --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 4935140..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,120 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "BikeNetLib" -copyright = "2026, BikeNetLib contributors" -author = "BikeNetLib contributors" - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -import os # noqa -import sys # noqa - -sys.path.insert(0, os.path.abspath("..")) -import bikenetlib # noqa - -# 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 -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", - "sphinx.ext.linkcode", - "sphinx.ext.mathjax", - "sphinx.ext.doctest", - "sphinx.ext.intersphinx", - "numpydoc", - "myst_nb", - "matplotlib.sphinxext.plot_directive", - "IPython.sphinxext.ipython_console_highlighting", - "sphinx_copybutton", - "sphinxext.opengraph", -] - -templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -# path to bib file with references -bibtex_bibfiles = ["_static/references.bib"] -bibtex_reference_style = "author_year" - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_static_path = ["_static"] - -### select html theme -# html_theme = 'alabaster' -html_theme = "pydata_sphinx_theme" - -html_theme_options = { - "github_url": "https://github.com/BikeNetKit/BikeNetLib", - "twitter_url": "notwitter.com", - "pygment_light_style": "tango", - "logo": { - "image_light": "logo.png", - "image_dark": "logo.png", - }, -} - -# 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_class_members_toctree = False -numpydoc_use_plots = True -autodoc_typehints = "none" - -# -- Extension configuration ------------------------------------------------- -nbsphinx_prolog = r""" -{% set docname = env.doc2path(env.docname, base=None) %} - -.. only:: html - - .. role:: raw-html(raw) - :format: html - - .. note:: - - | This page was generated from `{{ docname }}`__. - | Interactive online version: :raw-html:`Binder badge` - - __ https://github.com/BikeNetKit/BikeNetLib/blob/master/docs/{{ docname }} -""" # noqa: E501 - - -def linkcode_resolve(domain, info): - def find_source(): - # try to find the file and line number, based on code from numpy: - # https://github.com/numpy/numpy/blob/master/doc/source/conf.py#L286 - obj = sys.modules[info["module"]] - for part in info["fullname"].split("."): - obj = getattr(obj, part) - import inspect - import os - - fn = inspect.getsourcefile(obj) - fn = os.path.relpath(fn, start=os.path.dirname(bikenetlib.__file__)) - source, lineno = inspect.getsourcelines(obj) - return fn, lineno, lineno + len(source) - 1 - - if domain != "py" or not info["module"]: - return None - try: - filename = "BikeNetLib/%s#L%d-L%d" % find_source() # noqa: UP031 - except Exception: - filename = info["module"].replace(".", "/") + ".py" - tag = "main" if "+" in release else ("v" + release) - return f"https://github.com/BikeNetKit/BikeNetLib/blob/{tag}/{filename}" diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..83cf06c --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..6944a6b --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +furo==2025.12.19 diff --git a/docs/source/_static/css/dataframe.css b/docs/source/_static/css/dataframe.css new file mode 100644 index 0000000..3ef8220 --- /dev/null +++ b/docs/source/_static/css/dataframe.css @@ -0,0 +1,38 @@ +/* Style pandas DataFrame HTML from myst-nb outputs */ +div.cell_output table.dataframe { + border: none; + border-collapse: collapse; + border-spacing: 0; + margin: 1em 0; + font-size: 0.9em; + max-width: 100%; + overflow-x: auto; + display: block; +} + +div.cell_output table.dataframe thead { + border-bottom: 1px solid var(--color-foreground-border); +} + +div.cell_output table.dataframe tr, +div.cell_output table.dataframe th, +div.cell_output table.dataframe td { + text-align: right; + vertical-align: middle; + padding: 0.4em 0.6em; + line-height: 1.3; + border: none; + white-space: nowrap; +} + +div.cell_output table.dataframe th { + font-weight: 600; +} + +div.cell_output table.dataframe tbody tr:nth-child(odd) { + background: color-mix(in srgb, var(--color-background-secondary) 80%, transparent); +} + +div.cell_output table.dataframe tbody tr:hover { + background: color-mix(in srgb, var(--color-brand-primary) 12%, transparent); +} \ No newline at end of file diff --git a/docs/source/_static/favicon.png b/docs/source/_static/favicon.png new file mode 100644 index 0000000..064924c Binary files /dev/null and b/docs/source/_static/favicon.png differ diff --git a/docs/changelog.md b/docs/source/changelog.md similarity index 99% rename from docs/changelog.md rename to docs/source/changelog.md index da2a996..9af004c 100644 --- a/docs/changelog.md +++ b/docs/source/changelog.md @@ -1,13 +1,16 @@ # Changelog + ## Version 0.7.2 (2026-10-18) - 🐛 Fixed tqdm import + ## Version 0.7.1 (2026-10-17) - 🐛 Fixed io.silent + ## Version 0.7.0 (2026-10-16) - 📝 Added consolidate.md for an overview of potential functions @@ -17,6 +20,7 @@ - 👷 Added test_io - ➕ Added tqdm dependency + ## Version 0.6.0 (2026-10-10) - ✨ Added and polished shared utils functions @@ -27,6 +31,7 @@ - ⬆️ Updated actions versions - ⬆️ Added Python 3.15 support + ## Version 0.5.0 (2026-05-22) - ✨ Initial release ✨ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..2e5a99f --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,197 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "BikeNetLib" +copyright = "2026, BikeNetLib contributors" +author = "BikeNetLib contributors" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +import os # noqa +import sys # noqa +from pathlib import Path +from tomllib import load as toml_load + +sys.path.insert(0, os.path.abspath("../..")) +import bikenetlib # noqa + +# 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 +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.linkcode", + "sphinx.ext.mathjax", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "numpydoc", + "myst_nb", + "matplotlib.sphinxext.plot_directive", + "IPython.sphinxext.ipython_console_highlighting", + "sphinx_copybutton", + "sphinxext.opengraph", +] +source_suffix = { + '.rst': 'restructuredtext', + '.ipynb': 'myst-nb', + '.myst': 'myst-nb', +} +ogp_site_url = 'https://docs.bikenetkit.org/GrowBikeNet/' +ogp_image = '_static/logo_growbikenet_og.jpg' +ogp_custom_meta_tags = [ + '', +] +myst_enable_extensions = ["html_admonition"] +nb_execution_mode = 'auto' +nb_execution_allow_errors = False # Let's be strict so we don't publish completely broken docs +nb_execution_timeout = 5 # 120 for rebuild, 5 for preexecuted +nb_output_stderr = 'remove' # For debugging, it is better to 'show'! If errors should be hidden, 'remove' + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output +html_static_path = ["_static"] +html_css_files = [ + 'css/dataframe.css', +] + +### select html theme +html_theme = "furo" + +html_logo = "_static/logo_bikenetlib.svg" +html_favicon = "_static/favicon.png" +html_theme_options = { + "sidebar_hide_name": True, + "source_repository": "https://github.com/BikeNetKit/BikeNetLib/", + "source_branch": "main", + "source_directory": "docs/source/", + "top_of_page_buttons": ["view", "edit"], + "navigation_with_keys": True, + "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": "Linkedin", + "url": "https://www.linkedin.com/company/bikenetkit", + "html": """ + + + + """, + "class": "", + }, + { + "name": "Mastodon", + "url": "https://fosstodon.org/@bikenetkit", + "html": """ + + + + + """, + "class": "", + }, + { + "name": "Bluesky", + "url": "https://bsky.app/profile/bikenetkit.bsky.social", + "html": """ + + + + """, + "class": "", + }, + { + "name": "GitHub", + "url": "https://github.com/BikeNetKit/BikeNetLib", + "html": """ + + + + """, + "class": "", + }, + ], +} + +# Generate the API documentation when building +autosummary_generate = True +autosummary_imported_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" + +# -- Extension configuration ------------------------------------------------- +nbsphinx_prolog = r""" +{% set docname = env.doc2path(env.docname, base=None) %} + +.. only:: html + + .. role:: raw-html(raw) + :format: html + + .. note:: + + | This page was generated from `{{ docname }}`__. + | Interactive online version: :raw-html:`Binder badge` + + __ https://github.com/BikeNetKit/BikeNetLib/blob/master/docs/{{ docname }} +""" + + +def linkcode_resolve(domain, info): + def find_source(): + # try to find the file and line number, based on code from numpy: + # https://github.com/numpy/numpy/blob/master/doc/source/conf.py#L286 + obj = sys.modules[info["module"]] + for part in info["fullname"].split("."): + obj = getattr(obj, part) + import inspect + import os + + fn = inspect.getsourcefile(obj) + fn = os.path.relpath(fn, start=os.path.dirname(bikenetlib.__file__)) + source, lineno = inspect.getsourcelines(obj) + return fn, lineno, lineno + len(source) - 1 + + if domain != "py" or not info["module"]: + return None + try: + filename = "BikeNetLib/%s#L%d-L%d" % find_source() # noqa: UP031 + except Exception: + filename = info["module"].replace(".", "/") + ".py" + tag = "main" if "+" in release else ("v" + release) + return f"https://github.com/BikeNetKit/BikeNetLib/blob/{tag}/{filename}" diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 0000000..c80ab42 --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,39 @@ +Getting started +=============== + +Get Started in 4 Steps +---------------------- + +1. Install BikeNetLib by following the :doc:`installation` guide. + +2. To check that the installation worked, run the :doc:`mwe`. + +3. Walk through illustrative examples of BikeNetLib's features on our :doc:`usage` pages. + +4. Consult the :doc:`reference_user` for complete details on using the package. + +Also, if you're not already familiar with `OSMnx`_ and `GeoPandas`_, make sure you read their user guides as BikeNetLib uses their data structures. + +.. _overview-of-bikenetlib: + +Overview of BikeNetLib +---------------------- + +BikeNetLib is built on top of `OSMnx`_ and `GeoPandas`_. It is imported as ``bnl`` and comes with several building blocks: + +- ``bnl.io`` – Input and output +- ``bnl.utils`` – Utilities +- ``bnl.viz`` – Visualization +- ``bnl.osm`` – OpenStreetMap constants + + +To try it out, run the: + +.. toctree:: + :maxdepth: 1 + + Minimum working example + + +.. _GeoPandas: https://geopandas.org +.. _OSMnx: https://osmnx.readthedocs.io \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..7977595 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,67 @@ +.. BikeNetLib documentation master file, created by + sphinx-quickstart on Thu Feb 12 15:01:19 2026. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +BikeNetLib |version| documentation +=================================== + +The Python package ``bikenetlib`` is BikeNetKit's core utility package. It offers general utilities for working with bicycle networks, which also forms the core of many upstream packages in the BikeNetKit family, like `GrowBikeNet `__, `FixBikeNet `__, or `LinkBikeNet `__. It is hosted on `Github `__, part of `BikeNetKit `__. + +When to use +----------- + +BikeNetLib provides utilities for working with bicycle networks, from OpenStreetMap custom filters for selecting protected bicycle infrastructure, to functions for routing or importing/exporting network data. If you don't find a function that you need, please `let us know `__ or help us implement it. + +Setup and use +------------- + +To set up BikeNetLib, see the :doc:`installation` page. +To use BikeNetLib, the :doc:`getting_started` page +is a good place to start. Various usage examples are walked through on the :doc:`usage` page. For technical documentation, consult the :doc:`reference_user`. + +Origin +------ + +The source code is inspired by different origins, mostly including code from research projects in the BikeNetKit family. + +Contributing +------------ + +If you want to contribute to the development of BikeNetLib, please read the +`CONTRIBUTING.md `__ +file. + +Supported by +------------ + +Development of BikeNetKit/BikeNetLib is supported by the Innovation Fund Denmark, the EU HORIZON grant JUST STREETS, and the Data Science Section of IT University of Copenhagen. + +|Innovation Fund Denmark|    |European Union|   |JUST STREETS| + +Developed by |NERDS| + +.. |Innovation Fund Denmark| image:: https://raw.githubusercontent.com/BikeNetKit/.github/refs/heads/main/profile/_static/logo_innovationfund.png + :target: https://innovationsfonden.dk/en +.. |European Union| image:: https://raw.githubusercontent.com/BikeNetKit/.github/refs/heads/main/profile/_static/logo_eu.png + :target: https://commission.europa.eu/index_en +.. |JUST STREETS| image:: https://raw.githubusercontent.com/BikeNetKit/.github/refs/heads/main/profile/_static/logo_juststreets.png + :target: https://www.just-streets.eu/ +.. |NERDS| image:: https://raw.githubusercontent.com/BikeNetKit/.github/refs/heads/main/profile/_static/logo_nerds.png + :width: 280px + :target: https://www.nerds.itu.dk + + +Documentation contents +---------------------- + +.. toctree:: + :maxdepth: 1 + + Home + installation + getting_started + usage + reference_user + reference_developer + changelog diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..94ef030 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,148 @@ +============= +Installation +============= + +The easy way +~~~~~~~~~~~~ + +The recommended way to install BikeNetLib is using `conda `__ (or the faster `mamba `__) via the `conda-forge` channel: + +:: + + conda install bikenetlib -c conda-forge + +For more installation options, see below. + +With pip +~~~~~~~~ + +BikeNetLib can also be installed with pip, if all dependencies can be installed as well: + +:: + + pip install bikenetlib + +.. warning:: + + We do not recommend using pip, because you need to make sure that all dependencies of bikenetlib are installed correctly. Using conda, see `above <#the-easy-way>`__, avoids the need to compile the dependencies yourself. + + +Environment installations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creating a new environment is not strictly necessary, but given that installing other geospatial packages from different channels may cause dependency conflicts, it can be good practice to install in a clean environment starting fresh. + +The main step is to set up a virtual environment ``bnlenv`` in which to +install the package, and then to use or run the environment. Use either of the methods below. + +With conda +^^^^^^^^^^ + +Installation with `conda `__ (or the faster `mamba `__). The following commands create the ``bnlenv`` environment, configures it to install packages always from conda-forge, and installs BikeNetLib in it: + +:: + + conda create -n bnlenv + conda activate bnlenv + conda config --env --add channels conda-forge + conda config --env --set channel_priority strict + conda install python=3 bikenetlib + +With Pixi +^^^^^^^^^ + +The fastest and cleanest way to install BikeNetLib is via `Pixi `__: + +:: + + pixi init + pixi add bikenetlib + +Then use the Pixi environment as so: + +:: + + pixi shell + +.. note:: + + The first time you run code with Pixi, it might take a minute longer, as Pixi resolves the environment’s dependencies only at this point. + + +Run bikenetlib in Jupyter lab +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After having set up the environment `above <#environment-installations>`__, if you wish to run +bikenetlib via `JupyterLab `__, +follow the corresponding instructions below. + +With conda +^^^^^^^^^^ + +Using `conda `__ (or the faster `mamba `__), run: + +:: + + conda activate bnlenv + ipython kernel install --user --name=bnlenv + conda deactivate + jupyter lab + +Once Jupyter lab opens, switch the kernel (Kernel > Change Kernel > +bnlenv) + +With Pixi +^^^^^^^^^ + +Once you are in the Pixi shell, see `above <#with-pixi>`__, simply run jupyter lab: + +:: + + jupyter lab + +With pip +^^^^^^^^ + +Using pip, run: + +:: + + pip install --user ipykernel + python -m ipykernel install --user --name=bnlenv + jupyter lab + +Once Jupyter lab opens, switch the kernel (Kernel > Change Kernel > +bnlenv) + +Development installation +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to develop the project, `clone this +repository `__ +and create the environment via `Pixi `__ and the +``environment-dev.yml`` file: + +:: + + pixi init --import environment-dev.yml + +The development environment is called ``bnlenvdev``. At this point you can run bikenetlib in the environment, for example as +such: + +:: + + pixi run python examples/mwe.py + +.. note:: + + The first time you run code with Pixi, it might take a minute longer, as Pixi resolves the environment’s dependencies only at this point. + +Alternatively, start a pixi shell: + +:: + + pixi shell + +Make sure to also +read `our contribution +guidelines `__. diff --git a/docs/source/mwe.ipynb b/docs/source/mwe.ipynb new file mode 100644 index 0000000..5576f01 --- /dev/null +++ b/docs/source/mwe.ipynb @@ -0,0 +1,199 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + "# Minimum working example\n", + "This notebook runs a minimum working example with bikenetlib." + ] + }, + { + "cell_type": "markdown", + "id": "1", + "metadata": {}, + "source": [ + "## Import bikenetlib" + ] + }, + { + "cell_type": "markdown", + "id": "66e59357-7987-4e0c-b5fa-8a261d3fedec", + "metadata": {}, + "source": [ + "The standard way of importing bikenetlib:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "2", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [ + "remove-output" + ] + }, + "outputs": [], + "source": [ + "import bikenetlib as bnl" + ] + }, + { + "cell_type": "markdown", + "id": "3", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + "## Use `bnl.io`" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "4", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "outputs": [ + { + "data": { + "text/plain": [ + "'lhospitaletdellobregat'" + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "bnl.io.slugify(\"L'Hospitalet De Llobregat\")" + ] + }, + { + "cell_type": "markdown", + "id": "e9983455-b873-48fc-8ac0-c5a11ab4bc5a", + "metadata": {}, + "source": [ + "## Use `bnl.osm`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fedbaa27-95ba-43fa-a04f-f7f5e5d5aedf", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [ + "remove-output" + ] + }, + "outputs": [], + "source": [ + "import osmnx as ox\n", + "g = ox.graph_from_point(\n", + " (55.68208,12.52404),\n", + " dist=400,\n", + " custom_filter=bnl.osm.PBI_CUSTOM_FILTER,\n", + ")\n", + "ox.plot_graph(g, node_size=0)" + ] + }, + { + "cell_type": "markdown", + "id": "a5a3c563-7932-4254-ab52-9790e8dcc586", + "metadata": {}, + "source": [ + "## Use `bnl.utils`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d1ee4b0a-cb54-445c-914c-f70c9f16d664", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "bnl.utils.get_principal_bearing(g)" + ] + }, + { + "cell_type": "markdown", + "id": "8f1a3c9e-5c16-41ca-b822-e5e30ccc5180", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + "See the [Usage docs](https://docs.bikenetkit.org/BikeNetLib/usage/) for detailed explanations." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.15.0" + }, + "widgets": { + "application/vnd.jupyter.widget-state+json": { + "state": {}, + "version_major": 2, + "version_minor": 0 + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/reference_developer.rst b/docs/source/reference_developer.rst new file mode 100644 index 0000000..cd6bbd3 --- /dev/null +++ b/docs/source/reference_developer.rst @@ -0,0 +1,46 @@ +Developer reference +=================== + +This is the complete developer reference for the BikeNetLib package. If you are looking for an introduction to BikeNetLib, read the :doc:`getting_started` guide. + +The standard way to import the BikeNetLib package is via ``import bikenetlib as bnl``. + + +bikenetlib.constants +-------------------- + +.. automodule:: bikenetlib.constants + :members: + :private-members: + + +bikenetlib.io +------------- + +.. automodule:: bikenetlib.io + :members: + :private-members: + + +bikenetlib.osm +-------------- + +.. automodule:: bikenetlib.osm + :members: + :private-members: + + +bikenetlib.utils +---------------- + +.. automodule:: bikenetlib.utils + :members: + :private-members: + + +bikenetlib.viz +-------------- + +.. automodule:: bikenetlib.viz + :members: + :private-members: diff --git a/docs/source/reference_user.rst b/docs/source/reference_user.rst new file mode 100644 index 0000000..23dd1b0 --- /dev/null +++ b/docs/source/reference_user.rst @@ -0,0 +1,41 @@ +User reference +============== + +This is the user reference for the BikeNetLib package. If you are looking for an introduction to BikeNetLib, read the :doc:`getting_started` guide. + +The standard way to import the BikeNetLib package is via ``import bikenetlib as bnl``. + + +bikenetlib.constants +--------------------- + +.. automodule:: bikenetlib.constants + :members: + + +bikenetlib.io +------------- + +.. automodule:: bikenetlib.io + :members: + + +bikenetlib.osm +-------------- + +.. automodule:: bikenetlib.osm + :members: + + +bikenetlib.utils +---------------- + +.. automodule:: bikenetlib.utils + :members: + + +bikenetlib.viz +-------------- + +.. automodule:: bikenetlib.viz + :members: diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..5c47dfb --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,6 @@ +Usage +===== + +After having checked the :doc:`mwe`, the following pages walk you through the ideas, concepts, and features of BikeNetLib, by showcasing illustrative examples of real cities. + +To be written. \ No newline at end of file diff --git a/environment-dev.yml b/environment-dev.yml index e5a32f8..22b96f7 100644 --- a/environment-dev.yml +++ b/environment-dev.yml @@ -20,6 +20,7 @@ dependencies: - pre-commit - jupyterlab - pixi-kernel + - bikenetlib # To import in docs notebooks - pip: # not available via conda-forge: - sphinx-copybutton diff --git a/examples/mwe.ipynb b/examples/mwe.ipynb new file mode 100644 index 0000000..5576f01 --- /dev/null +++ b/examples/mwe.ipynb @@ -0,0 +1,199 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + "# Minimum working example\n", + "This notebook runs a minimum working example with bikenetlib." + ] + }, + { + "cell_type": "markdown", + "id": "1", + "metadata": {}, + "source": [ + "## Import bikenetlib" + ] + }, + { + "cell_type": "markdown", + "id": "66e59357-7987-4e0c-b5fa-8a261d3fedec", + "metadata": {}, + "source": [ + "The standard way of importing bikenetlib:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "2", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [ + "remove-output" + ] + }, + "outputs": [], + "source": [ + "import bikenetlib as bnl" + ] + }, + { + "cell_type": "markdown", + "id": "3", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + "## Use `bnl.io`" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "4", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "outputs": [ + { + "data": { + "text/plain": [ + "'lhospitaletdellobregat'" + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "bnl.io.slugify(\"L'Hospitalet De Llobregat\")" + ] + }, + { + "cell_type": "markdown", + "id": "e9983455-b873-48fc-8ac0-c5a11ab4bc5a", + "metadata": {}, + "source": [ + "## Use `bnl.osm`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fedbaa27-95ba-43fa-a04f-f7f5e5d5aedf", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [ + "remove-output" + ] + }, + "outputs": [], + "source": [ + "import osmnx as ox\n", + "g = ox.graph_from_point(\n", + " (55.68208,12.52404),\n", + " dist=400,\n", + " custom_filter=bnl.osm.PBI_CUSTOM_FILTER,\n", + ")\n", + "ox.plot_graph(g, node_size=0)" + ] + }, + { + "cell_type": "markdown", + "id": "a5a3c563-7932-4254-ab52-9790e8dcc586", + "metadata": {}, + "source": [ + "## Use `bnl.utils`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d1ee4b0a-cb54-445c-914c-f70c9f16d664", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "bnl.utils.get_principal_bearing(g)" + ] + }, + { + "cell_type": "markdown", + "id": "8f1a3c9e-5c16-41ca-b822-e5e30ccc5180", + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, + "source": [ + "See the [Usage docs](https://docs.bikenetkit.org/BikeNetLib/usage/) for detailed explanations." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.15.0" + }, + "widgets": { + "application/vnd.jupyter.widget-state+json": { + "state": {}, + "version_major": 2, + "version_minor": 0 + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}