lucaferranti · lucaferranti · Oct 25, 2024 · Oct 25, 2024 · Oct 25, 2024 · Oct 25, 2024
diff --git a/.lychee.toml b/.lychee.toml
@@ -1,5 +1,6 @@
 exclude = [
   "@ref",
+  "@cite",
   "^https://github.com/.*/releases/tag/v.*$",
   "^https://doi.org/FIXME$",
   "^https://lucaferranti.github.io/DedekindCutArithmetic.jl/stable$",

diff --git a/README.md b/README.md
@@ -1,21 +1,23 @@
 # DedekindCutArithmetic.jl
 
-[![license: MIT][license-img]][license-url]
-[![Stable Documentation][stabledoc-img]][stabledoc-url]
-[![In development documentation][devdoc-img]][devdoc-url]
-[![Build Status][ci-img]][ci-url]
-[![Coverage][cov-img]][cov-url]
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
-[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages][colprac-img]][colprac-url]
-[![SciML Code Style][style-img]][style-url]
+|**Info**|**Documentation**|**Build status**|**Contributing**|
+|:------:|:--------------:|:---------------:|:--------------:|
+|[![version][ver-img]][ver-url] [![license: MIT][license-img]][license-url]<br/>[![DOI][doi-img]][doi-url]|[![Stable Documentation][stabledoc-img]][stabledoc-url] [![In development documentation][devdoc-img]][devdoc-url]|[![Build Status][ci-img]][ci-url] [![Coverage][cov-img]][cov-url]<br/>[![pkgeval-img]][pkgeval-url]|[![Contributor Covenant][coc-img]][coc-url] [![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages][colprac-img]][colprac-url]<br/>[![SciML Code Style][style-img]][style-url]|
 
 A Julia library for exact real arithmetic using [Dedekind cuts](https://en.wikipedia.org/wiki/Dedekind_cut) and [Abstract Stone Duality](https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=02c685856371aac16ce81bf7467ffc4d533d48ff). Heavily inspired by the [Marshall](https://github.com/andrejbauer/marshall) programming language.
 
-## Installation
+## Table of Content
 
-1. If you haven't already, install Julia. The easiest way is to install [Juliaup](https://github.com/JuliaLang/juliaup#installation). This allows to easily install and manage julia versions.
+- [💾 Installation](https://github.com/lucaferranti/DedekindCutArithmetic.jl#--installation)
+- [🌱 Quickstart example](https://github.com/lucaferranti/DedekindCutArithmetic.jl#--quickstart-example)
+- [📚 Documentation](https://github.com/lucaferranti/DedekindCutArithmetic.jl#--documentation)
+- [🤝 Contributing](https://github.com/lucaferranti/DedekindCutArithmetic.jl#--contributing)
 
-2. Open the terminal and start a julia session by typing `julia`.
+## 💾 Installation
+
+1. If you haven't already, install Julia. The easiest way is to install [Juliaup](https://github.com/JuliaLang/juliaup#installation). This allows to easily install and manage Julia versions.
+
+2. Open the terminal and start a Julia session by typing `julia`.
 
 3. Install the library by typing
 
@@ -31,9 +33,9 @@ A Julia library for exact real arithmetic using [Dedekind cuts](https://en.wikip
 
 5. That's it, have fun!
 
-## Quickstart example
+## 🌱 Quickstart example
 
-The following snippet shows how to define the squareroot of a number and the maximum of a function $f: [0, 1] \rightarrow \mathbb{R}$ using Dedekind cuts. It also shows this definition is actually computable and can be used to give a tight rigorous bound of the value.
+The following snippet shows how to define the square root of a number and the maximum of a function $f: [0, 1] \rightarrow \mathbb{R}$ using Dedekind cuts. It also shows this definition is actually computable and can be used to give a tight rigorous bound on the value.
 
 ```julia
 using DedekindCutArithmetic
@@ -59,28 +61,36 @@ refine!(fmax) # evaluate to 53 bits of precision by default
 # [0.24999999999999992, 0.25000000000000006]
 ```
 
-## Documentation
+## 📚 Documentation
 
 - [**STABLE**][stabledoc-url]: Documentation of the latest release
 - [**DEV**][devdoc-url]: Documentation of the in-development version on main
 
-## Contributing
+A good starting point is the [beginner tutorial](https://lucaferranti.github.io/DedekindCutArithmetic.jl/dev/tutorial/)
+
+## 🤝 Contributing
 
 Contributions are welcome! Here is a small decision tree with useful links. More details in the [contributor's guide](https://lucaferranti.github.io/DedekindCutArithmetic.jl/dev/90-contributing).
 
 - There is a [discussion section](https://github.com/lucaferranti/DedekindCutArithmetic.jl/discussions) on GitHub. You can use the [helpdesk](https://github.com/lucaferranti/DedekindCutArithmetic.jl/discussions/categories/helpdesk) category to ask for help on how to use the software or the [show and tell](https://github.com/lucaferranti/DedekindCutArithmetic.jl/discussions/categories/show-and-tell) category to simply share with the world your work using DedekindCutArithmetic.jl
 
 - If you find a bug or want to suggest a new feature, [open an issue](https://github.com/lucaferranti/DedekindCutArithmetic.jl/issues).
 
-- You are also encouraged to send pull requests (PRs). For small changes, it is ok to open a PR directly. For bigger changes, it is advisable to discuss it in an issue first. Before opening a PR, make sure to check the [contributor's guide](https://lucaferranti.github.io/DedekindCutArithmetic.jl/dev/90-contributing).
+- You are also encouraged to send pull requests (PRs). For small changes, it is ok to open a PR directly. For bigger changes, it is advisable to discuss it in an issue first. Before opening a PR, make sure to check the [developer's guide](https://lucaferranti.github.io/DedekindCutArithmetic.jl/dev/91-developer).
 
-## Copyright
+## 📜 Copyright
 
 - Copyright (c) 2024 [Luca Ferranti](https://github.com/lucaferranti), released under MIT license
 
+[ver-img]: https://juliahub.com/docs/DedekindCutArithmetic/version.svg
+[ver-url]: https://github.com/lucaferranti/DedekindCutArithmetic.jl/releases/latest
+
 [license-img]: https://img.shields.io/badge/license-MIT-yellow.svg
 [license-url]: https://github.com/lucaferranti/DedekindCutArithmetic.jl/blob/main/LICENSE
 
+[doi-img]: https://zenodo.org/badge/876330838.svg
+[doi-url]: https://doi.org/10.5281/zenodo.13989059
+
 [stabledoc-img]: https://img.shields.io/badge/docs-stable-blue.svg
 [stabledoc-url]: https://lucaferranti.github.io/DedekindCutArithmetic.jl/stable
 
@@ -93,6 +103,12 @@ Contributions are welcome! Here is a small decision tree with useful links. More
 [cov-img]: https://codecov.io/gh/lucaferranti/DedekindCutArithmetic.jl/branch/main/graph/badge.svg
 [cov-url]: https://codecov.io/gh/lucaferranti/DedekindCutArithmetic.jl
 
+[pkgeval-img]: https://juliaci.github.io/NanosoldierReports/pkgeval_badges/D/DedekindCutArithmetic.svg
+[pkgeval-url]: https://juliaci.github.io/NanosoldierReports/pkgeval_badges/D/DedekindCutArithmetic.html
+
+[coc-img]: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
+[coc-url]: https://github.com/lucaferranti/DedekindCutArithmetic.jl/blob/main/CODE_OF_CONDUCT.md
+
 [colprac-img]: https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet
 [colprac-url]: https://github.com/SciML/ColPrac
 

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,7 +1,9 @@
 [deps]
+DedekindCutArithmetic = "a9cf20ff-59c8-5762-8ce8-520b700dfeff"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+IntervalArithmetic = "d1acc4aa-44c8-5952-acd4-ba5d80a2a253"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
-DedekindCutArithmetic = "a9cf20ff-59c8-5762-8ce8-520b700dfeff"
 
 [compat]
 Documenter = "1"
diff --git a/docs/make.jl b/docs/make.jl
@@ -8,22 +8,33 @@ Pkg.activate(@__DIR__)
 using Documenter
 using DedekindCutArithmetic
 
+using DocumenterCitations
+
+bib = CitationBibliography(
+    joinpath(@__DIR__, "src", "refs.bib");
+    style = :numeric
+)
+
 ###############
 # CREATE HTML #
 ###############
 
 makedocs(;
     modules = [DedekindCutArithmetic], authors = "Luca Ferranti",
     sitename = "DedekindCutArithmetic.jl",
-    doctest = false, checkdocs = :exports,
+    doctest = false, checkdocs = :exports, plugins = [bib],
     format = Documenter.HTML(;
         prettyurls = IS_CI, collapselevel = 1,
-        canonical = "https://lucaferranti.github.io/DedekindCutArithmetic.jl"),
+        canonical = "https://lucaferranti.github.io/DedekindCutArithmetic.jl",
+        assets = String["assets/citations.css"]
+    ),
     pages = [
         "Home" => "index.md",
+        "Tutorial" => "tutorial.md",
         "API" => "api.md",
         "Contributing" => ["90-contributing.md", "91-developer.md"],
-        "Release notes" => "changelog.md"
+        "Release notes" => "changelog.md",
+        "References" => "references.md"
     ])
 
 ##########

diff --git a/docs/src/90-contributing.md b/docs/src/90-contributing.md
@@ -27,7 +27,7 @@ We follow the [ColPrac guide for collaborative practices](https://github.com/Sci
 
 If you found an issue that interests you, comment on that issue what your plans are.
 If the solution to the issue is clear, you can immediately create a pull request.
-Otherwise, say what yourfollow proposed solution is and wait for a discussion around it.
+Otherwise, say what your proposed solution is and wait for a discussion around it.
 
 For small changes (typos, trivial bug fixes) it is ok to open a PR directly even without an associated issue. For non-trivial changes, please open an issue first.
 

diff --git a/docs/src/91-developer.md b/docs/src/91-developer.md
@@ -3,7 +3,7 @@
 !!! note "Contributing guidelines"
     If you haven't, please read the [Contributing guidelines](90-contributing.md) first.
 
-If you want to make contributions to this package that involves code, then this guide is for you.
+If you want to make contributions to this package, then this guide is for you.
 
 ## First time clone
 
@@ -12,9 +12,9 @@ If you want to make contributions to this package that involves code, then this
 
 If this is the first time you work with this repository, follow the instructions below to clone the repository.
 
-1. Fork this repo
-2. Clone your repo (this will create a `git remote` called `origin`)
-3. Add this repo as a remote:
+1. Fork this repository
+2. Clone your fork (this will create a `git remote` called `origin`)
+3. Add the original repository as a remote:
 
    ```bash
    git remote add upstream https://github.com/lucaferranti/DedekindCutArithmetic.jl
@@ -23,18 +23,21 @@ If this is the first time you work with this repository, follow the instructions
 This will ensure that you have two remotes in your git: `origin` and `upstream`.
 You will create branches and push to `origin`, and you will fetch and update your local `main` branch from `upstream`.
 
+!!! warning "Warning"
+    From now on, these instructions assume you are in the `DedekindCutArithmetic.jl` folder
+
 ## Linting and formatting
 
 Install a plugin on your editor to use [EditorConfig](https://editorconfig.org).
 This will ensure that your editor is configured with important formatting settings.
 
 We use [https://pre-commit.com](https://pre-commit.com) to run the linters and formatters.
-In particular, the Julia code is formatted using [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl), so please install it globally first:
+In particular, the Julia code is formatted using [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl), so please install it globally first as follows (the following snippet is copy-pastable into the REPL)
 
 ```julia-repl
-julia> # Press ]
-pkg> activate
-pkg> add JuliaFormatter
+julia> import Pkg;
+pkg> Pkg.activate();
+pkg> Pkg.add("JuliaFormatter")
 ```
 
 To install `pre-commit`, we recommend using [pipx](https://pipx.pypa.io) as follows:
@@ -68,6 +71,12 @@ pkg> activate .
 pkg> test
 ```
 
+Each test file is also stand-alone, hence to run a specific file you can `include` that from the REPL
+
+```julia-repl
+julia> include("test/test-cuts.jl")
+```
+
 ## Working on a new issue
 
 We try to keep a linear history in this repo, so it is important to keep your branches up-to-date.
@@ -126,13 +135,21 @@ We try to keep a linear history in this repo, so it is important to keep your br
 
 ## Building and viewing the documentation locally
 
-To build the documentation locally, simply run
+The first time you want to build the documentation locally, you will need to install all needed dependencies. To do so, run
+
+```bash
+julia docs/setup.jl
+```
+
+This needs to be done the fist time (i.e. if you don't have a `docs/Manifest.toml` file). The setup script needs to be rerun only if some external libraries used in the documentation example change.
+
+Next, you can build the documentation locally by running
 
 ```bash
 julia docs/liveserver.jl
 ```
 
-This will build the documentation and open a preview in your browser. Whenever you make some changes in the documentation files, the preview will also update live.
+This will open a preview of the documentation in your browser and watch the documentation source files, meaning the preview will automatically update on every documentation file change.
 
 ## Making a new release
 

diff --git a/docs/src/assets/citations.css b/docs/src/assets/citations.css
@@ -0,0 +1,17 @@
+.citation dl {
+    display: grid;
+    grid-template-columns: max-content auto; }
+  .citation dt {
+    grid-column-start: 1; }
+  .citation dd {
+    grid-column-start: 2;
+    margin-bottom: 0.75em; }
+  .citation ul {
+   padding: 0 0 2.25em 0;
+   margin: 0;
+   list-style: none !important;}
+  .citation ul li {
+   text-indent: -2.25em;
+   margin: 0.33em 0.5em 0.5em 2.25em;}
+  .citation ol li {
+   padding-left:0.75em;}
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -6,11 +6,11 @@ CurrentModule = DedekindCutArithmetic
 
 A Julia library for exact real arithmetic using [Dedekind cuts](https://en.wikipedia.org/wiki/Dedekind_cut) and [Abstract Stone Duality](https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=02c685856371aac16ce81bf7467ffc4d533d48ff). Heavily inspired by the [Marshall](https://github.com/andrejbauer/marshall) programming language.
 
-## Installation
+## 💾 Installation
 
-1. If you haven't already, install Julia. The easiest way is to install [Juliaup](https://github.com/JuliaLang/juliaup#installation). This allows to easily install and manage julia versions.
+1. If you haven't already, install Julia. The easiest way is to install [Juliaup](https://github.com/JuliaLang/juliaup#installation). This allows to easily install and manage Julia versions.
 
-2. Open the terminal and start a julia session by typing `julia`.
+2. Open the terminal and start a Julia session by typing `julia`.
 
 3. Install the library by typing
 
@@ -26,9 +26,9 @@ A Julia library for exact real arithmetic using [Dedekind cuts](https://en.wikip
 
 5. That's it, have fun!
 
-## Quickstart example
+## 🌱 Quickstart example
 
-The following snippet shows how to define the squareroot of a number and the maximum of a function $f: [0, 1] \rightarrow \mathbb{R}$ using Dedekind cuts. It also shows this definition is actually computable and can be used to give a tight rigorous bound of the value.
+The following snippet shows how to define the square root of a number and the maximum of a function $f: [0, 1] \rightarrow \mathbb{R}$ using Dedekind cuts. It also shows this definition is actually computable and can be used to give a tight rigorous bound on the value.
 
 ```julia
 using DedekindCutArithmetic
@@ -54,15 +54,15 @@ refine!(fmax) # evaluate to 53 bits of precision by default
 # [0.24999999999999992, 0.25000000000000006]
 ```
 
-## Contributing
+## 🤝 Contributing
 
 Contributions are welcome! Here is a small decision tree with useful links. More details in the [contributor's guide](https://lucaferranti.github.io/DedekindCutArithmetic.jl/dev/90-contributing).
 
 - There is a [discussion section](https://github.com/lucaferranti/DedekindCutArithmetic.jl/discussions) on GitHub. You can use the [helpdesk](https://github.com/lucaferranti/DedekindCutArithmetic.jl/discussions/categories/helpdesk) category to ask for help on how to use the software or the [show and tell](https://github.com/lucaferranti/DedekindCutArithmetic.jl/discussions/categories/show-and-tell) category to simply share with the world your work using DedekindCutArithmetic.jl
 
 - If you find a bug or want to suggest a new feature, [open an issue](https://github.com/lucaferranti/DedekindCutArithmetic.jl/issues).
 
-- You are also encouraged to send pull requests (PRs). For small changes, it is ok to open a PR directly. For bigger changes, it is advisable to discuss it in an issue first. Before opening a PR, make sure to check the [contributor's guide](https://lucaferranti.github.io/DedekindCutArithmetic.jl/dev/90-contributing).
+- You are also encouraged to send pull requests (PRs). For small changes, it is ok to open a PR directly. For bigger changes, it is advisable to discuss it in an issue first. Before opening a PR, make sure to check the [developer's guide](https://lucaferranti.github.io/DedekindCutArithmetic.jl/dev/91-developer).
 
 ## Copyright
 

diff --git a/docs/src/references.md b/docs/src/references.md
@@ -0,0 +1,4 @@
+# References
+
+```@bibliography
+```
diff --git a/docs/src/refs.bib b/docs/src/refs.bib
@@ -0,0 +1,27 @@
+@article{bauer2009dedekind,
+  title={The Dedekind reals in abstract Stone duality},
+  author={Bauer, Andrej and Taylor, Paul},
+  journal={Mathematical structures in computer science},
+  volume={19},
+  number={4},
+  pages={757--838},
+  year={2009},
+  publisher={Cambridge University Press}
+}
+
+@inproceedings{bauer2008efficient,
+  title={Efficient computation with Dedekind reals},
+  author={Bauer, Andrej},
+  booktitle={Fifth International Conference on Computability and Complexity in Analysis,(Eds. V Brattka, R Dillhage, T Grubba, A Klutch), Hagen, Germany},
+  year={2008},
+  organization={Citeseer}
+}
+
+@misc{marshall,
+  author = {Bauer, Andrej},
+  title = {Marshall},
+  year = {2012},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  url = {https://github.com/andrejbauer/marshall},
+}