[documentation] Add tutorials & citation (#192)

* [documentation] Add tutorials

* Use the option push_preview=true

* Use JuliaFormatter on docs/make.jl

* Update tutorials.md

* Refresh tutorial, add citations

---------

Co-authored-by: Guillaume Dalle <[email protected]>

Author: amontoison

CITATION.cff

@@ -28,3 +28,23 @@ keywords:
   - automatic differentiation
   - julia programming language
 license: MIT
+preferred-citation:
+  authors:
+    - given-names: Alexis
+      family-names: Montoison
+      orcid: 'https://orcid.org/0000-0002-3403-5450'
+    - given-names: Guillaume
+      family-names: Dalle
+      orcid: 'https://orcid.org/0000-0003-4866-1687'
+    - given-names: Assefaw
+      family-names: Gebremedhin
+      orcid: 'https://orcid.org/0000-0001-5383-8032'
+  title: "Revisiting Sparse Matrix Coloring and Bicoloring"
+  year: 2025
+  type: article
+  url: 'https://arxiv.org/abs/2505.07308'
+  identifiers:
+    - type: doi
+      value: 10.48550/arXiv.2505.07308
+      description: Arxiv
+  abstract: "Sparse matrix coloring and bicoloring are fundamental building blocks of sparse automatic differentiation. Bicoloring is particularly advantageous for rectangular Jacobian matrices with at least one dense row and column. Indeed, in such cases, unidirectional row or column coloring demands a number of colors equal to the number of rows or columns. We introduce a new strategy for bicoloring that encompasses both direct and substitution-based decompression approaches. Our method reformulates the two variants of bicoloring as star and acyclic colorings of an augmented symmetric matrix. We extend the concept of neutral colors, previously exclusive to bicoloring, to symmetric colorings, and we propose a post-processing routine that neutralizes colors to further reduce the overall color count. We also present the Julia package SparseMatrixColorings, which includes these new bicoloring algorithms alongside all standard coloring methods for sparse derivative matrix computation. Compared to ColPack, the Julia package also offers enhanced implementations for star and acyclic coloring, vertex ordering, as well as decompression."

README.md

@@ -5,6 +5,7 @@
 [![Dev Documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://gdalle.github.io/SparseMatrixColorings.jl/dev/)
 [![Coverage](https://codecov.io/gh/gdalle/SparseMatrixColorings.jl/branch/main/graph/badge.svg)](https://app.codecov.io/gh/gdalle/SparseMatrixColorings.jl)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/JuliaDiff/BlueStyle)
+[![arXiv](https://img.shields.io/badge/arXiv-2505.07308-b31b1b.svg)](https://arxiv.org/abs/2505.07308)
 [![DOI](https://zenodo.org/badge/801999408.svg)](https://zenodo.org/doi/10.5281/zenodo.11314275)
 
 Coloring algorithms for sparse Jacobian and Hessian matrices.
@@ -19,7 +20,11 @@ pkg> add SparseMatrixColorings
 
 ## Background
 
-The algorithms implemented in this package are taken from the following articles:
+The algorithms implemented in this package are described in the following preprint:
+
+- [_Revisiting Sparse Matrix Coloring and Bicoloring_](https://arxiv.org/abs/2505.07308), Montoison et al. (2025)
+
+and inspired by previous works:
 
 - [_What Color Is Your Jacobian? Graph Coloring for Computing Derivatives_](https://epubs.siam.org/doi/10.1137/S0036144504444711), Gebremedhin et al. (2005)
 - [_New Acyclic and Star Coloring Algorithms with Application to Computing Hessians_](https://epubs.siam.org/doi/abs/10.1137/050639879), Gebremedhin et al. (2007)
@@ -35,5 +40,18 @@ Some parts of the articles (like definitions) are thus copied verbatim in the do
 
 ## Citing
 
-Please cite this software using the provided `CITATION.cff` file.
+Please cite this software using the provided `CITATION.cff` file or the `.bib` entry below:
+
+```bibtex
+@unpublished{montoison2025revisitingsparsematrixcoloring,
+      title={Revisiting Sparse Matrix Coloring and Bicoloring}, 
+      author={Alexis Montoison and Guillaume Dalle and Assefaw Gebremedhin},
+      year={2025},
+      eprint={2505.07308},
+      archivePrefix={arXiv},
+      primaryClass={math.NA},
+      url={https://arxiv.org/abs/2505.07308}, 
+}
+```
+
 The link <https://zenodo.org/doi/10.5281/zenodo.11314275> resolves to the latest version on Zenodo.

docs/make.jl

@@ -12,9 +12,14 @@ makedocs(;
     sitename="SparseMatrixColorings.jl",
     format=Documenter.HTML(),
     pages=[
-        "Home" => "index.md", "api.md", "Developer Documentation" => ["dev.md", "vis.md"]
+        "Home" => "index.md",
+        "tutorial.md",
+        "api.md",
+        "Developer Documentation" => ["dev.md", "vis.md"],
     ],
     plugins=[links],
 )
 
-deploydocs(; repo="github.com/gdalle/SparseMatrixColorings.jl", devbranch="main")
+deploydocs(;
+    repo="github.com/gdalle/SparseMatrixColorings.jl", push_preview=true, devbranch="main"
+)