edsger 0.0.15__tar.gz → 0.1.0__tar.gz

edsger-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ release ]
+  pull_request:
+    branches: [ release ]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    
+    - name: Install documentation dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r docs/requirements.txt
+    
+    - name: Build documentation
+      run: |
+        cd docs
+        make html
+    
+    - name: Upload documentation artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation-html
+        path: docs/build/html/
+    
+    - name: Deploy to GitHub Pages (on release branch)
+      if: github.ref == 'refs/heads/release' && github.event_name == 'push'
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html
+        publish_branch: gh-pages

{edsger-0.0.15 → edsger-0.1.0}/.github/workflows/tests.yml

@@ -9,14 +9,13 @@ jobs:
   test:
     strategy:
       matrix:
-        os: [        os: [ubuntu-22.04, windows-2022, macos-14]
-        ]
+        os: [ubuntu-22.04, windows-2022, macos-14]
         python-version: ["3.11"]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

{edsger-0.0.15 → edsger-0.1.0}/.gitignore

@@ -45,9 +45,22 @@ sdist/*
 docs/api/*
 docs/_rst/*
 docs/_build/*
+docs/build/*
 cover/*
 MANIFEST
 
+# Documentation backup and temporary folders
+docs_BCKP/
+docs_old/
+site/
+tmp/
+
+# Credentials and config
+.pypirc
+
+# MkDocs (unused)
+mkdocs.yml
+
 # Per-project virtualenvs
 .venv*/
 .conda*/

edsger-0.1.0/.readthedocs.yaml

@@ -0,0 +1,27 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Explicitly set the version of Python and its requirements
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - requirements: requirements.txt
+    - method: pip
+      path: .
+
+# Optional but recommended, pin the Python requirements used to build docs
+formats:
+  - pdf
+  - htmlzip

{edsger-0.0.15/src/edsger.egg-info → edsger-0.1.0}/PKG-INFO

@@ -1,11 +1,12 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: edsger
-Version: 0.0.15
+Version: 0.1.0
 Summary: Graph algorithms in Cython.
 Author-email: François Pacull <francois.pacull@architecture-performance.fr>
 Maintainer-email: François Pacull <francois.pacull@architecture-performance.fr>
 License: MIT License
 Project-URL: Repository, https://github.com/aetperf/Edsger
+Project-URL: Documentation, https://edsger.readthedocs.io
 Keywords: python,graph,shortest path,Dijkstra
 Platform: any
 Classifier: Development Status :: 4 - Beta
@@ -31,6 +32,7 @@ Provides-Extra: doc
 Requires-Dist: sphinx; extra == "doc"
 Requires-Dist: sphinx_design; extra == "doc"
 Requires-Dist: sphinx_rtd_theme; extra == "doc"
+Dynamic: license-file
 
 
 ![Tests Status](https://github.com/aetperf/edsger/actions/workflows/tests.yml/badge.svg?branch=release)

{edsger-0.0.15 → edsger-0.1.0}/docs/Makefile

@@ -17,4 +17,4 @@ help:
 # 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)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

edsger-0.1.0/docs/requirements.txt

@@ -0,0 +1,19 @@
+# Documentation build requirements
+sphinx>=7.0.0
+myst-parser>=2.0.0
+sphinx-autodoc-typehints>=1.22.0
+sphinx-copybutton>=0.5.0
+furo>=2023.5.20
+
+# Required for building Cython extensions during doc build
+numpy>=1.26
+pandas>=2.0
+Cython>=3.0
+setuptools>=61.0
+
+# Optional but recommended
+sphinx-design>=0.5.0
+sphinx-tabs>=3.4.0
+
+# ReadTheDocs specific
+readthedocs-sphinx-search>=0.3.0

edsger-0.1.0/docs/source/api.md

@@ -0,0 +1,136 @@
+# API Reference
+
+This section provides detailed documentation for all public classes and functions in Edsger.
+
+## edsger.path Module
+
+### Dijkstra Class
+
+The main class for performing Dijkstra's shortest path algorithm.
+
+#### Constructor Parameters
+
+- `edges`: pandas.DataFrame containing the graph edges
+- `tail`: Column name for edge source nodes (default: 'tail')
+- `head`: Column name for edge destination nodes (default: 'head')
+- `weight`: Column name for edge weights (default: 'weight')
+- `orientation`: Either 'out' (single-source) or 'in' (single-target) (default: 'out')
+- `check_edges`: Whether to validate edge data (default: False)
+- `permute`: Whether to optimize node indexing (default: False)
+
+#### Methods
+
+##### run
+
+```python
+def run(self, vertex_idx, path_tracking=False, return_inf=True, 
+        return_series=False, heap_length_ratio=1.0)
+```
+
+Runs the shortest path algorithm from/to the specified vertex.
+
+**Parameters:**
+- `vertex_idx`: Source/target vertex index
+- `path_tracking`: Whether to track paths for reconstruction (default: False)
+- `return_inf`: Return infinity for unreachable vertices (default: True)
+- `return_series`: Return results as pandas Series (default: False)
+- `heap_length_ratio`: Heap size as fraction of vertices (default: 1.0)
+
+**Returns:**
+- Array or Series of shortest path lengths
+
+##### get_path
+
+```python
+def get_path(self, vertex_idx)
+```
+
+Reconstructs the shortest path to/from a vertex (requires `path_tracking=True`).
+
+**Parameters:**
+- `vertex_idx`: Destination/source vertex index
+
+**Returns:**
+- Array of vertex indices forming the path
+
+##### get_vertices
+
+```python
+def get_vertices(self)
+```
+
+Returns all vertices in the graph.
+
+**Returns:**
+- Array of vertex indices
+
+### Examples
+
+#### Basic Usage
+
+```python
+from edsger.path import Dijkstra
+import pandas as pd
+
+# Create a graph
+edges = pd.DataFrame({
+    'tail': [0, 0, 1],
+    'head': [1, 2, 2],
+    'weight': [1, 4, 2]
+})
+
+# Initialize Dijkstra
+dijkstra = Dijkstra(edges)
+
+# Find shortest paths from vertex 0
+paths = dijkstra.run(vertex_idx=0)
+```
+
+#### With Path Tracking
+
+```python
+# Enable path tracking
+paths = dijkstra.run(vertex_idx=0, path_tracking=True)
+
+# Get the actual path to vertex 2
+path = dijkstra.get_path(vertex_idx=2)
+```
+
+#### Custom Parameters
+
+```python
+# Create with custom settings
+dijkstra = Dijkstra(
+    edges,
+    orientation='in',
+    check_edges=True,
+    permute=True
+)
+
+# Run with custom parameters
+paths = dijkstra.run(
+    vertex_idx=2,
+    return_series=True,
+    heap_length_ratio=0.5
+)
+```
+
+### Graph Data Format
+
+Edsger expects graph data as a pandas DataFrame with the following structure:
+
+| Column | Type    | Description                          |
+|--------|---------|--------------------------------------|
+| tail   | int     | Source vertex ID                     |
+| head   | int     | Destination vertex ID                |
+| weight | float   | Edge weight (must be non-negative)   |
+
+Example:
+```python
+edges = pd.DataFrame({
+    'tail': [0, 0, 1, 2],
+    'head': [1, 2, 2, 3],
+    'weight': [1.0, 4.0, 2.0, 1.0]
+})
+```
+

{edsger-0.0.15 → edsger-0.1.0}/docs/source/conf.py

@@ -3,7 +3,6 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -13,7 +12,7 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../../src/edsger/"))
+sys.path.insert(0, os.path.abspath("../../src/"))
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -22,6 +21,16 @@ project = "Edsger"
 copyright = "2024, Architecture & Performance"
 author = "Francois Pacull"
 
+# Get version from the package
+try:
+    from edsger._version import __version__
+    release = __version__
+    version = __version__
+except ImportError:
+    # Fallback if import fails
+    release = "0.0.15"
+    version = "0.0.15"
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -44,5 +53,22 @@ extensions = [
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
     "sphinx_design",
+    "myst_parser",  # Enable MyST parser for Markdown
+    "sphinx_copybutton",
 ]
+
+# MyST parser configuration
+myst_enable_extensions = [
+    "deflist",
+    "tasklist",
+    "html_admonition",
+    "html_image",
+]
+
+# Source suffix
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}

edsger-0.1.0/docs/source/contributing.md

@@ -0,0 +1,69 @@
+# Contributing to Edsger
+
+We welcome contributions to the Edsger library! This document provides guidelines for contributing to the project.
+
+## Getting Started
+
+### Development Environment
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/aetperf/Edsger.git
+   cd Edsger
+   ```
+
+2. Create a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. Install development dependencies:
+   ```bash
+   pip install -r requirements-dev.txt
+   pip install -e .
+   ```
+
+## Development Guidelines
+
+### Code Style
+
+- Follow PEP 8 for Python code
+- Use meaningful variable and function names
+- Add docstrings to all public functions and classes
+- Keep functions focused and concise
+
+### Testing
+
+- Write tests for all new features
+- Ensure all tests pass before submitting a pull request
+- Aim for high test coverage
+
+### Documentation
+
+- Update documentation for any new features or changes
+- Use clear and concise language
+- Include examples where appropriate
+
+## Submitting Changes
+
+1. Fork the repository on GitHub
+2. Create a new branch for your feature or bugfix
+3. Make your changes and commit them with clear commit messages
+4. Push your branch to your fork
+5. Submit a pull request with a clear description of your changes
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+- A clear description of the problem
+- Steps to reproduce the issue
+- Expected vs actual behavior
+- System information (OS, Python version, etc.)
+
+## Questions?
+
+If you have questions about contributing, please open an issue on GitHub or contact the maintainers.
+
+Thank you for contributing to Edsger!

edsger-0.1.0/docs/source/index.md

@@ -0,0 +1,54 @@
+---
+github_url: https://github.com/aetperf/Edsger
+---
+
+# Edsger
+
+*Graph algorithms in Cython*
+
+Welcome to the Edsger documentation! Edsger is a Python library for efficient graph algorithms implemented in Cython. The library currently focuses on shortest path algorithms, with Dijkstra's algorithm fully implemented and additional algorithms planned for future releases.
+
+## Key Features
+
+- Fast implementation of Dijkstra's algorithm
+- Support for both single-source and single-target shortest paths
+- Easy integration with pandas DataFrames
+- Memory-efficient 4-ary heap implementation
+- Path tracking and reconstruction capabilities
+
+## Quick Links
+
+- [Installation](installation.md) - How to install Edsger
+- [Quick Start](quickstart.md) - Get started quickly with basic examples
+- [API Reference](api.md) - Complete API reference
+
+## Table of Contents
+
+```{toctree}
+:maxdepth: 2
+:caption: User Guide
+
+installation
+quickstart
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: API Reference
+
+api
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Development
+
+contributing
+```
+
+## Indices
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`
+

edsger-0.1.0/docs/source/installation.md

@@ -0,0 +1,148 @@
+# Installation Guide
+
+This guide will help you install the `edsger` package on your system.
+
+## Requirements
+
+Before you begin, ensure you have the following prerequisites:
+
+- Python 3.11 or higher
+- pip (Python package installer) or uv (recommended)
+- (Optional) git for installing from source
+
+## Method 1: Using Python venv + pip
+
+Create a virtual environment and install with pip:
+
+```bash
+# Create a virtual environment
+python -m venv edsger-env
+
+# Activate the virtual environment
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install edsger
+pip install edsger
+```
+
+## Method 2: Using uv (Recommended)
+
+[uv](https://github.com/astral-sh/uv) provides faster installation and better dependency resolution:
+
+```bash
+# Install uv if you haven't already
+pip install uv
+
+# Create a virtual environment with uv
+uv venv edsger-env
+
+# Activate the virtual environment
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install edsger
+uv pip install edsger
+```
+
+## Installing from Source
+
+If you prefer to install from source or contribute to development:
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/aetperf/Edsger.git
+cd Edsger
+```
+
+### 2. Using Python venv + pip
+
+```bash
+# Create and activate virtual environment
+python -m venv edsger-env
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install in editable mode
+pip install -e .
+```
+
+### 3. Using uv (Recommended)
+
+```bash
+# Create and activate virtual environment
+uv venv edsger-env
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install in editable mode
+uv pip install -e .
+```
+
+### 4. Verify the Installation
+
+Check that the installation was successful by importing the package in a Python shell:
+
+```python
+python
+>>> import edsger
+>>> edsger.__version__
+```
+
+You should see the version number of the `edsger` package.
+
+## Development Installation
+
+For contributors who need development dependencies:
+
+### Using Python venv + pip
+
+```bash
+# Create and activate virtual environment
+python -m venv edsger-env
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+pip install -e .
+```
+
+### Using uv (Recommended)
+
+```bash
+# Create and activate virtual environment
+uv venv edsger-env
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install development dependencies
+uv pip install -r requirements-dev.txt
+uv pip install -e .
+```
+
+## Troubleshooting
+
+### Module Not Found Error
+
+If you encounter a `ModuleNotFoundError`, make sure that:
+1. The `edsger` package is installed correctly
+2. You're using the correct Python environment
+3. The `PYTHONPATH` is set appropriately (if needed)
+
+### Compilation Issues
+
+If you experience compilation issues, ensure you have:
+- A working C compiler
+- NumPy installed
+- Cython >= 3.0 installed
+
+## Uninstallation
+
+To uninstall the `edsger` package:
+
+```bash
+pip uninstall edsger
+```
+
+## Getting Help
+
+For further assistance:
+- Check the [documentation](index.md)
+- Open an issue on [GitHub](https://github.com/aetperf/Edsger)
+- Contact the maintainer at [francois.pacull@architecture-performance.fr](mailto:francois.pacull@architecture-performance.fr)