Refactor (#11)

* Revamp CI scripts

* Structure source

* Remove example

* Revamp structures

* Fix broken tests due to randomness

* Newlines in yml

* Replace ccall with the macro

* Apply suggestions from code review

Co-authored-by: Alexis Montoison <[email protected]>

* Fix tests

---------

Co-authored-by: Alexis Montoison <[email protected]>

.JuliaFormatter.toml

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

.github/dependabot.yml

@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/Documentation.yml

@@ -0,0 +1,29 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v2
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

.github/workflows/TagBot.yml

@@ -4,6 +4,22 @@ on:
     types:
       - created
   workflow_dispatch:
+    inputs:
+      lookback:
+        default: "3"
+permissions:
+  actions: read
+  checks: read
+  contents: write
+  deployments: read
+  issues: read
+  discussions: read
+  packages: read
+  pages: read
+  pull-requests: read
+  repository-projects: read
+  security-events: read
+  statuses: read
 jobs:
   TagBot:
     if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
@@ -12,3 +28,6 @@ jobs:
       - uses: JuliaRegistries/TagBot@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
+          # Edit the following line to reflect the actual name of the GitHub Secret containing your private key
+          ssh: ${{ secrets.DOCUMENTER_KEY }}
+          # ssh: ${{ secrets.NAME_OF_MY_SSH_PRIVATE_KEY_SECRET }}

.github/workflows/Test.yml

@@ -0,0 +1,35 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+# needed to allow julia-actions/cache to delete old caches that it has created
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        julia-version: ['1.6', '1']
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.julia-version }}
+          arch: x64
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v4
+        with:
+          files: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false

.gitignore

@@ -1,2 +1,4 @@
 Manifest.toml
-
+/docs/build/
+/docs/src/index.md
+*.mtx

Project.toml

@@ -1,7 +1,7 @@
 name = "ColPack"
 uuid = "ffa27691-3a59-46ab-a8d4-551f45b8d401"
 authors = ["Michel Schanen <[email protected]>"]
-version = "0.3.0"
+version = "0.4.0"
 
 [deps]
 ColPack_jll = "f218ff0c-cb54-5151-80c4-c0f62c730ce6"
@@ -11,4 +11,7 @@ SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 
 [compat]
 ColPack_jll = "0.3.0"
+LinearAlgebra = "1"
+Random = "1"
+SparseArrays = "1"
 julia = "1.6"

README.md

@@ -1,32 +1,22 @@
 # ColPack
-[![][build-stable-img]][build-url]
 
-This is the Julia interface to [ColPack](https://github.com/CSCsw/ColPack).
+[![Build Status](https://github.com/michel2323/ColPack.jl/actions/workflows/Test.yml/badge.svg?branch=master)](https://github.com/michel2323/ColPack.jl/actions/workflows/Test.yml?query=branch%master)
+[![Dev Documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://michel2323.github.io/ColPack.jl/dev/)
 
-## Usage
-### Jacobian coloring by columns
-```julia
-using ColPack
-using SparseArrays
-
-# Example matrix/Jacobian
-A = [
-    [1.0 1.0 0.0 0.0 0.0];
-    [0.0 0.0 1.0 0.0 0.0];
-    [0.0 1.0 0.0 1.0 0.0];
-    [0.0 0.0 0.0 1.0 1.0];
-]
+This is the Julia interface to [ColPack](https://github.com/CSCsw/ColPack) for graph and matrix coloring.
 
-A = sparse(A)
+## Getting started
 
-# Create adjacency matrix for column coloring
-adjA = ColPack.matrix2adjmatrix(A; partition_by_rows=false)
+You can install this package by running the following command in a Julia Pkg REPL (the necessary binaries will be downloaded automatically):
 
-coloring = ColPackColoring(adjA, d1_coloring(), random_ordering())
-println("Number of colors: ", length(unique(get_colors(coloring))))
-println("Vector of vertex colors: ", get_colors(coloring))
+```julia
+pkg> add ColPack
 ```
 
+Take a look at the tutorial in the documentation to get a feel for what you can do.
+
+## Mathematical background
+
+To understand the link between graph coloring and automatic differentiation, read the following survey:
 
-[build-url]: https://github.com/michel2323/ColPack.jl/actions?query=workflow
-[build-stable-img]: https://github.com/michel2323/ColPack.jl/workflows/Run%20tests/badge.svg?branch=master
+> [_What Color Is Your Jacobian? Graph Coloring for Computing Derivatives_](https://epubs.siam.org/doi/10.1137/S0036144504444711), Gebremedhin et al. (2005)

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+ColPack = "ffa27691-3a59-46ab-a8d4-551f45b8d401"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -0,0 +1,21 @@
+using Documenter
+using ColPack
+
+cp(joinpath(@__DIR__, "..", "README.md"), joinpath(@__DIR__, "src", "index.md"); force=true)
+
+makedocs(;
+    modules=[ColPack],
+    authors="Michel Schanen",
+    sitename="ColPack.jl",
+    format=Documenter.HTML(),
+    pages=[
+        "Home" => "index.md",
+        "Tutorial" => "tutorial.md",
+        "API reference" => "api.md",
+    ],
+)
+
+deploydocs(;
+    repo="github.com/michel2323/ColPack.jl",
+    devbranch="master",
+)

docs/src/api.md

@@ -0,0 +1,36 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# API reference
+
+## Entry points
+
+```@autodocs
+Modules = [ColPack]
+Pages = ["colpackcoloring.jl", "utils.jl"]
+Private = false
+```
+
+## Coloring method
+
+```@autodocs
+Modules = [ColPack]
+Pages = ["method.jl"]
+Private = false
+```
+
+## Coloring order
+
+```@autodocs
+Modules = [ColPack]
+Pages = ["order.jl"]
+Private = false
+```
+
+## Internals
+
+```@autodocs
+Modules = [ColPack]
+Public = false
+```

docs/src/tutorial.md

@@ -0,0 +1,44 @@
+# Tutorial
+
+## Jacobian coloring
+
+```jldoctest tuto
+julia> using ColPack, SparseArrays
+```
+
+```jldoctest tuto
+julia> J = sparse([
+           1 1 0 0 0
+           0 0 1 0 0
+           0 1 0 1 0
+           0 0 0 1 1
+       ]);
+
+julia> adjJ = ColPack.matrix2adjmatrix(J; partition_by_rows=false)
+5×5 SparseMatrixCSC{Float64, UInt32} with 6 stored entries:
+  ⋅   1.0   ⋅    ⋅    ⋅ 
+ 1.0   ⋅    ⋅   1.0   ⋅ 
+  ⋅    ⋅    ⋅    ⋅    ⋅ 
+  ⋅   1.0   ⋅    ⋅   1.0
+  ⋅    ⋅    ⋅   1.0   ⋅ 
+```
+
+```jldoctest tuto
+julia> coloring = ColPackColoring(adjJ, d1_coloring(), natural_ordering());
+
+julia> colors = get_colors(coloring)
+5-element Vector{Int64}:
+ 1
+ 2
+ 1
+ 1
+ 2
+
+julia> length(unique(colors)) == 2
+true
+```
+
+## Hessian coloring
+
+!!! warning
+    Work in progress