Move docs from readme to website, better testing (#34)

- Use Documenter to create a documentation website featuring the
docstrings and former README tutorial
- Add this build step to CI
- Test for code quality and formatting (indicated as broken because I
didn't want to overload this PR with formatting changes)

---------

Co-authored-by: Mathieu Besançon <mathieu.besancon@gmail.com>

Author: gdalle

.JuliaFormatter.toml

@@ -0,0 +1 @@
+style = "blue"

.codecov.yml

@@ -1,14 +1,15 @@
 name: CI
-env:
-  JULIA_NUM_THREADS: 2
 on:
-  pull_request:
-    branches:
-      - master
   push:
     branches:
       - master
-    tags: '*'
+    tags: ['*']
+  pull_request:
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
@@ -17,13 +18,11 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - 'nightly'
-          - '1'
           - '1.6'
+          - '1'
+          - 'nightly'
         os:
           - ubuntu-latest
-          - macos-latest
-          - windows-latest
         arch:
           - x64
     steps:
@@ -32,19 +31,31 @@ jobs:
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v1
-        env:
-          cache-name: cache-artifacts
-        with:
-          path: ~/.julia/artifacts
-          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-test-${{ env.cache-name }}-
-            ${{ runner.os }}-test-
-            ${{ runner.os }}-
+      - uses: julia-actions/cache@v1
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v1
+      - uses: codecov/codecov-action@v2
+        with:
+          files: lcov.info
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
         with:
-          file: lcov.info
+          version: '1'
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - run: |
+          julia --project=docs -e '
+            using Documenter: DocMeta, doctest
+            using SimpleWeightedGraphs
+            DocMeta.setdocmeta!(SimpleWeightedGraphs, :DocTestSetup, :(using SimpleWeightedGraphs); recursive=true)
+            doctest(SimpleWeightedGraphs)'

.github/workflows/CI.yml

@@ -1,4 +1,5 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
-Manifest.toml
+/Manifest.toml
+docs/build/

.gitignore

@@ -0,0 +1,8 @@
+@misc{SimpleWeightedGraphs.jl,
+	author  = {JuliaGraphs contributors},
+	title   = {SimpleWeightedGraphs.jl},
+	url     = {https://github.com/JuliaGraphs/SimpleWeightedGraphs.jl},
+	version = {v1.3.0},
+	year    = {2023},
+	month   = {2}
+}

CITATION.bib

@@ -1,14 +1,25 @@
 name = "SimpleWeightedGraphs"
 uuid = "47aef6b3-ad0c-573a-a1e2-d07658019622"
+authors = ["JuliaGraphs contributors"]
 version = "1.3.0"
 
 [deps]
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
 Graphs = "1.7"
 julia = "1"
+
+[extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Aqua", "Documenter", "Graphs", "JuliaFormatter", "LinearAlgebra", "Test"]

Project.toml

@@ -1,59 +1,11 @@
 # SimpleWeightedGraphs
 
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaGraphs.github.io/SimpleWeightedGraphs.jl/stable/)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaGraphs.github.io/SimpleWeightedGraphs.jl/dev/)
 [![Build Status](https://github.com/JuliaGraphs/SimpleWeightedGraphs.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/JuliaGraphs/SimpleWeightedGraphs.jl/actions/workflows/CI.yml?query=branch%3Amaster)
-[![codecov.io](http://codecov.io/github/JuliaGraphs/SimpleWeightedGraphs.jl/coverage.svg?branch=master)](http://codecov.io/github/JuliaGraphs/SimpleWeightedGraphs.jl?branch=master)
+[![Coverage](https://codecov.io/gh/JuliaGraphs/SimpleWeightedGraphs.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaGraphs/SimpleWeightedGraphs.jl)
+[![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 
-Edge-Weighted Graphs for [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl).
+Edge-weighted graphs compatible with [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl).
 
-Usage:
-```julia
-using Graphs, SimpleWeightedGraphs
-
-g = SimpleWeightedGraph(3)  # or use `SimpleWeightedDiGraph` for directed graphs
-add_edge!(g, 1, 2, 0.5)
-add_edge!(g, 2, 3, 0.8)
-add_edge!(g, 1, 3, 2.0)
-
-# get weight of edge from vertex 1 to vertex 2
-get_weight(g, 1, 2)
-
-# find the shortest path from vertex 1 to vertex 3 taking weights into account.
-enumerate_paths(dijkstra_shortest_paths(g, 1), 3)
-3-element Array{Int64,1}:
- 1
- 2
- 3
-
-# reweight the edge from 1 to 2
-add_edge!(g, 1, 2, 1.6)
-
-# rerun the shortest path calculation from 1 to 3
-enumerate_paths(dijkstra_shortest_paths(g, 1), 3)
-2-element Array{Int64,1}:
- 1
- 3
-
-# it's possible to build the graph from arrays of sources, destinations and weights
-sources = [1,2,1]
-destinations = [2,3,3]
-weights = [0.5, 0.8, 2.0]
-g = SimpleWeightedGraph(sources, destinations, weights)
-
-# the combine keyword handles repeated pairs (sum by default)
-g = SimpleWeightedGraph([1,2,1], [2,1,2], [1,1,1]; combine = +)
-g.weights[2,1] == g.weights[1,2] == 3 # true
-
-# WARNING: unexpected results might occur with non-associative combine functions
-
-# notice that weights are indexed by [destination, source]
-s = SimpleWeightedDiGraph([1,2,1], [2,1,2], [1,1,1]; combine = +)
-s.weights[1,2] == 1 # true
-s.weights[2,1] == 2 # true
-```
-
-Please pay attention to the fact that zero-weight edges are discarded by `add_edge!`.
-This is due to the way the graph is stored (a sparse matrix). [A possible workaround
-is to set a very small weight instead](https://stackoverflow.com/questions/48977068/how-to-add-free-edge-to-graph-in-lightgraphs-julia/48994712#48994712).
-
-Note that adding or removing vertices or edges from these graph types is not particularly performant;
-see [MetaGraphs.jl](https://github.com/JuliaGraphs/MetaGraphs.jl) for possible alternatives.
+See the [documentation](https://JuliaGraphs.github.io/SimpleWeightedGraphs.jl/dev/) for a tutorial.