Merge pull request #19 from PhilipMathieu/showcase

Add docs, build upgrades

.github/workflows/mkdocs.yml

@@ -0,0 +1,31 @@
+name: Build and Publish Docs
+on:
+  push:
+    branches:
+      - master
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

_version.py

@@ -0,0 +1,17 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = "0.0.2.dev15"
+__version_tuple__ = version_tuple = (0, 0, 2, "dev15")

docs/contributing.md

@@ -0,0 +1,23 @@
+# Contributing
+
+## Documentation
+
+Documentation is built with MkDocs - for full documentation visit [mkdocs.org](https://www.mkdocs.org). To install the packages needed for local development, run:
+```
+pip install graphreadability[docs]
+```
+
+This will install `mkdocs` (documentation generator), `mkdocs-material` (theme), `mkdocstrings` (plugin adding lots of cross-referencing abilities), and `mkdocstrings-python` (the additional handler needed for Python).
+
+### MkDocs Commands
+
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+### MkDocs Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

docs/index.md

@@ -0,0 +1,64 @@
+# graphreadability
+
+Python module for applying readability metrics to network and graph visualizations.
+
+## Credits
+Created by Philip Englund Mathieu, MS DS '24, as part of Northeastern University's Khoury College of Computer Sciences Research Apprenticeship program. Advised by Prof. Cody Dunne. For additional attributions, see [the dedicated references page](references.md).
+
+## Installation
+
+```
+pip install graphreadability
+```
+
+## Usage
+
+```python
+# Suggested import syntax
+import networkx as nx
+import graphreadability as gr
+
+# Create a basic graph using NetworkX
+G = nx.Graph()
+G.add_nodes_from(
+    [
+        (1, {"x": 1, "y": 1}),
+        (2, {"x": -1, "y": 1}),
+        (3, {"x": -1, "y": -1}),
+        (4, {"x": 1, "y": -1}),
+        (5, {"x": 2, "y": 1}),
+    ]
+)
+G.add_edges_from([(1, 2), (2, 3), (3, 4), (4, 2), (1, 3)])
+
+# Create a MetricsSuite to calculate readability metrics
+M = gr.MetricsSuite(G)
+
+# Calculate readability metrics
+M.calculate_metrics()
+
+# Print results
+M.pretty_print_metrics()
+```
+
+Expected Output:
+
+```
+--------------------------------------------------
+Metric                        Value     Weight
+--------------------------------------------------
+angular_resolution            0.312     1
+aspect_ratio                  0.667     1
+crossing_angle                1.000     1
+edge_crossing                 1.000     1
+edge_length                   0.829     1
+edge_orthogonality            0.600     1
+gabriel_ratio                 0.556     1
+neighbourhood_preservation    0.333     1
+node_orthogonality            0.417     1
+node_resolution               0.277     1
+node_uniformity               0.812     1
+--------------------------------------------------
+Evaluation using weighted_sum: 0.61855
+--------------------------------------------------
+```

docs/metrics.md

@@ -0,0 +1,5 @@
+# Supported Metrics
+
+This page documents the metrics included with the current version. The contents are generated directly from the `graphreadability.metrics.metrics.py`.
+
+::: graphreadability.metrics.metrics

docs/metricssuite.md

@@ -0,0 +1,3 @@
+# MetricsSuite
+
+::: graphreadability.MetricsSuite

docs/references.md

@@ -0,0 +1,8 @@
+# References
+
+Two papers served as primary references to this work:
+
+1. G. J. Mooney, H. C. Purchase, M. Wybrow, and S. G. Kobourov, “The Multi-Dimensional Landscape of Graph Drawing Metrics”.
+2. C. Dunne, S. I. Ross, B. Shneiderman, and M. Martino, “Readability metric feedback for aiding node-link visualization designers,” IBM Journal of Research and Development, vol. 59, no. 2/3, p. 14:1-14:16, Mar. 2015, doi: 10.1147/JRD.2015.2411412
+
+Additional thanks to Gavin Mooney, who shared the code accompanying [1] on GitHub and permitted my reuse.