upgrade to Documenter 1.0 (#33)

lucaferranti · web-flow · commit 9ea4f2055d19 · 2023-11-25T16:04:02.000+02:00
* upgrade to Documenter 1.0

* update doc

* update citation informations

* fix docs
diff --git a/CITATION.bib b/CITATION.bib
@@ -1,8 +1,7 @@
-@misc{ferranti2023fuzzylogicjl,
-      title={FuzzyLogic.jl: a Flexible Library for Efficient and Productive Fuzzy Inference}, 
-      author={Luca Ferranti and Jani Boutellier},
-      year={2023},
-      eprint={2306.10316},
-      archivePrefix={arXiv},
-      primaryClass={cs.AI}
-}
+@INPROCEEDINGS{ferranti2023fuzzylogicjl,
+  author={Ferranti, Luca and Boutellier, Jani},
+  booktitle={2023 IEEE International Conference on Fuzzy Systems (FUZZ)}, 
+  title={FuzzyLogic.jl: A Flexible Library for Efficient and Productive Fuzzy Inference}, 
+  year={2023},
+  pages={1-5},
+  doi={10.1109/FUZZ52849.2023.10309777}}
diff --git a/CITATION.cff b/CITATION.cff
@@ -8,20 +8,22 @@ type: software
 authors:
   - given-names: Luca
     family-names: Ferranti
+    orcid: "https://orcid.org/0000-0001-5588-0920"
 identifiers:
   - type: doi
     value: 10.5281/zenodo.7570243
 repository-code: 'https://github.com/lucaferranti/FuzzyLogic.jl'
 license: MIT
 preferred-citation:
-  type: article
+  type: proceedings
   authors:
   - family-names: "Ferranti"
     given-names: "Luca"
     orcid: "https://orcid.org/0000-0001-5588-0920"
   - family-names: "Boutellier"
     given-names: "Jani"
     orcid: "https://orcid.org/0000-0001-7606-3655"
-  journal: "arxiv:2306.10316"
+  journal: "2023 IEEE International Conference on Fuzzy Systems (FUZZ)"
+  doi: 10.1109/FUZZ52849.2023.10309777
   title: "FuzzyLogic.jl: a Flexible Library for Efficient and Productive Fuzzy Inference"
   year: 2023
diff --git a/README.md b/README.md
@@ -4,35 +4,53 @@
 |:------:|:--------------:|:---------------:|:--------------:|:----------:|
 |[![version][ver-img]][ver-url]|[![CI Status][ci-img]][ci-url]|[![Stable docs][stable-img]][stable-url]|[![contributing guidelines][contrib-img]][contrib-url]|[![bibtex][bibtex-img]][bibtex-url]
 |[![Licese: MIT][license-img]][license-url]|[![Coverage][cov-img]][cov-url]|[![Dev docs][dev-img]][dev-url]|[![SciML Code Style][style-img]][style-url]|[![paper][paper-img]][paper-url]|
-|[![downloads][download-img]][download-url]|[![pkgeval-img]][pkgeval-url]||[![gitter-chat][chat-img]][chat-url]|[![zenodo][zenodo-img]][zenodo-url]
+|[![downloads][download-img]][download-url]|[![pkgeval-img]][pkgeval-url]|[![JuliaCon video][video-img]][video-url]|[![gitter-chat][chat-img]][chat-url]|[![zenodo][zenodo-img]][zenodo-url]
 
 <p align="center">
 <img src="./docs/src/assets/logo.svg"/>
 </p>
 
 A Julia library for fuzzy logic and applications.
 
+If you use this in your research, please cite it as
+
+```bibtex
+@INPROCEEDINGS{ferranti2023fuzzylogicjl,
+  author={Ferranti, Luca and Boutellier, Jani},
+  booktitle={2023 IEEE International Conference on Fuzzy Systems (FUZZ)}, 
+  title={FuzzyLogic.jl: A Flexible Library for Efficient and Productive Fuzzy Inference}, 
+  year={2023},
+  pages={1-5},
+  doi={10.1109/FUZZ52849.2023.10309777}}
+```
+
+## Features
+
+- **Rich!** Mamdani and Sugeno inference systems, both Type-1 and Type-2, several [membership functions](https://lucaferranti.github.io/FuzzyLogic.jl/stable/api/memberships) and [algoritms options](https://lucaferranti.github.io/FuzzyLogic.jl/stable/api/fis) available.
+- **Compatible!** Read your models from [IEC 61131-7 Fuzzy Control Language](https://ffll.sourceforge.net/fcl.htm), [IEEE 1855-2016 Fuzzy Markup Language](https://en.wikipedia.org/wiki/Fuzzy_markup_language) and Matlab Fuzzy toolbox `.fis` files.
+- **Expressive!** Clear Domain Specific Language to write your model as human readable Julia code
+- **Productive!** Several visualization tools to help debug and tune your model.
+- **Portable!** Compile your final model to Julia code.
+
 ## Installation
 
-To install the package, open a Julia session and run
+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 manage julia versions.
+
+2. Open the terminal and start a julia session by simply typing `julia`
+
+3. Install the library by typing
 
 ```julia
 using Pkg; Pkg.add("FuzzyLogic")
 ```
 
-the package can then be loaded with
+4. The package can now be loaded (in the interactive REPL or in a script file) with the command
 
 ```julia
 using FuzzyLogic
 ```
 
-## Features
-
-- **Rich!** Mamdani and Sugeno inference systems, both Type-1 and Type-2, several [membership functions](https://lucaferranti.github.io/FuzzyLogic.jl/stable/api/memberships) and [algoritms options](https://lucaferranti.github.io/FuzzyLogic.jl/stable/api/fis) available.
-- **Compatible!** Read your models from [IEC 61131-7 Fuzzy Control Language](https://ffll.sourceforge.net/fcl.htm), [IEEE 1855-2016 Fuzzy Markup Language](https://en.wikipedia.org/wiki/Fuzzy_markup_language) and Matlab Fuzzy toolbox `.fis` files.
-- **Expressive!** Clear Domain Specific Language to write your model as human readable Julia code
-- **Productive!** Several visualization tools to help debug and tune your model.
-- **Portable!** Compile your final model to Julia code.
+5. That's it, have fun!
 
 ## Quickstart example
 
@@ -71,6 +89,8 @@ fis(service=1, food=2)
 - [**STABLE**][stable-url]: Documentation of the latest release
 - [**DEV**][dev-url]: Documentation of the version on main
 
+[![JuliaCon video](https://img.youtube.com/vi/6WfX3e-aOBc/0.jpg)](https://youtu.be/6WfX3e-aOBc)
+
 ## Contributing
 
 Contributions are welcome! Here is a small decision tree with useful links. 
@@ -102,6 +122,9 @@ Contributions are welcome! Here is a small decision tree with useful links.
 [dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
 [dev-url]: https://lucaferranti.github.io/FuzzyLogic.jl/dev/
 
+[video-img]: https://img.shields.io/badge/JuliaCon-video-red.svg
+[video-url]: https://www.youtube.com/watch?v=6WfX3e-aOBc
+
 [ci-img]: https://github.com/lucaferranti/FuzzyLogic.jl/actions/workflows/CI.yml/badge.svg?branch=main
 [ci-url]: https://github.com/lucaferranti/FuzzyLogic.jl/actions/workflows/CI.yml?query=branch%3Amain
 
@@ -123,7 +146,7 @@ Contributions are welcome! Here is a small decision tree with useful links.
 [bibtex-img]: https://img.shields.io/badge/BibTeX-citation-orange
 [bibtex-url]: https://github.com/lucaferranti/FuzzyLogic.jl/blob/main/CITATION.bib
 
-[paper-img]: https://img.shields.io/badge/arxiv-paper-blue
+[paper-img]: https://img.shields.io/badge/FUZZIEEE-paper-blue
 [paper-url]: https://arxiv.org/abs/2306.10316
 
 [zenodo-img]: https://img.shields.io/badge/Zenodo-archive-blue
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -12,6 +12,7 @@ TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
 
 [compat]
 DocThemeIndigo = "0.1.3"
+Documenter = "1"
 ImageCore = "0.9.4"
 ImageFiltering = "0.7.3"
 Literate = "2.14"
diff --git a/docs/make.jl b/docs/make.jl
@@ -22,7 +22,7 @@ const nbdir = joinpath(@__DIR__, "src", "notebooks") # output directory for note
 # fix edit links (only locally)
 function fix_edit_link(content)
     replace(content,
-            "EditURL = \"<unknown>" => "EditURL = \"https://github.com/lucaferranti/FuzzyLogic.jl/blob/main")
+        "EditURL = \"<unknown>" => "EditURL = \"https://github.com/lucaferranti/FuzzyLogic.jl/blob/main")
 end
 
 # Adds link from markdown to notebook.
@@ -41,9 +41,9 @@ for (root, _, files) in walkdir(jldir), file in files
     ipath = joinpath(root, file)
     opath = splitdir(replace(ipath, jldir => mddir))[1]
     Literate.markdown(ipath, opath;
-                      preprocess = notebook_link(file),
-                      postprocess = IS_CI ? identity : fix_edit_link,
-                      credit = false)
+        preprocess = notebook_link(file),
+        postprocess = IS_CI ? identity : fix_edit_link,
+        credit = false)
 
     Literate.notebook(ipath, nbdir; execute = IS_CI, credit = false)
 end
@@ -55,32 +55,35 @@ end
 function generate_memberships()
     mfs = subtypes(FuzzyLogic.AbstractMembershipFunction)
     open(joinpath(@__DIR__, "src", "api", "memberships.md"), "w") do f
-        write(f, """```@setup memberships
-        using FuzzyLogic
-        using Plots
-        ```
+        write(f,
+            """```@setup memberships
+   using FuzzyLogic
+   using Plots
+   ```
 
-        # Membership functions
+   # Membership functions
 
-        """)
+   """)
         for mf in mfs
             sec = string(mf)[1:(end - 2)] * " membership function"
-            write(f, """## $sec
+            write(f,
+                """## $sec
 
-            ```@docs
-            $mf
-            ```
+       ```@docs
+       $mf
+       ```
 
-            """)
+       """)
             docstring = match(r"```julia\nmf = (.+)\n```", string(Docs.doc(mf)))
             if !isnothing(docstring)
                 mfex = only(docstring.captures)
-                write(f, """
-                ```@example memberships
-                plot($mfex, 0, 10) # hide
-                ```
+                write(f,
+                    """
+           ```@example memberships
+           plot($mfex, 0, 10) # hide
+           ```
 
-                """)
+           """)
             end
         end
     end
@@ -94,32 +97,35 @@ function generate_norms()
     ]
     titles = ["Conjuction", "Disjunction", "Implication"]
     open(joinpath(@__DIR__, "src", "api", "logical.md"), "w") do f
-        write(f, """```@setup logicals
-        using FuzzyLogic
-        using Plots
-        ```
-
-        # Logical connectives
-        """)
+        write(f,
+            """```@setup logicals
+   using FuzzyLogic
+   using Plots
+   ```
+
+   # Logical connectives
+   """)
         for (t, c) in zip(titles, connectives)
-            write(f, """
-            ## $t methods
+            write(f,
+                """
+       ## $t methods
 
-            """)
+       """)
 
             for ci in c
-                write(f, """
-                ### $(nameof(ci))
-
-                ```@docs
-                $ci
-                ```
-
-                ```@example logicals
-                x = y = 0:0.01:1 # hide
-                contourf(x, y, (x, y) -> $ci()(x, y)) # hide
-                ```
-                """)
+                write(f,
+                    """
+           ### $(nameof(ci))
+
+           ```@docs
+           $ci
+           ```
+
+           ```@example logicals
+           x = y = 0:0.01:1 # hide
+           contourf(x, y, (x, y) -> $ci()(x, y)) # hide
+           ```
+           """)
             end
         end
     end
@@ -136,41 +142,41 @@ generate_norms()
 ###############
 
 makedocs(;
-         modules = [FuzzyLogic], authors = "Luca Ferranti",
-         sitename = "FuzzyLogic.jl",
-         doctest = false, checkdocs = :exports, strict = true,
-         format = Documenter.HTML(;
-                                  assets = [
-                                      DocThemeIndigo.install(FuzzyLogic),
-                                      "assets/favicon.ico",
-                                  ],
-                                  prettyurls = IS_CI, collapselevel = 1,
-                                  canonical = "https://lucaferranti.github.io/FuzzyLogic.jl"),
-         pages = [
-             "Home" => "index.md",
-             "Tutorials" => [
-                 "Build a Mamdani inference system" => "tutorials/mamdani.md",
-                 "Build a Sugeno inference system" => "tutorials/sugeno.md",
-                 "Build a type-2 inference system" => "tutorials/type2.md",
-             ],
-             "Applications" => [
-                 "Edge detection" => "applications/edge_detector.md",
-             ],
-             "API" => [
-                 "Inference system API" => [
-                     "Types" => "api/fis.md",
-                     "Logical connectives" => "api/logical.md",
-                     "Aggregation methods" => "api/aggregation.md",
-                     "Defuzzification methods" => "api/defuzzification.md",
-                 ],
-                 "Membership functions" => "api/memberships.md",
-                 "Reading/Writing" => "api/readwrite.md",
-                 "Learning fuzzy models" => "api/genfis.md",
-                 "Plotting" => "api/plotting.md",
-             ],
-             "Contributor's Guide" => "contributing.md",
-             "Release notes" => "changelog.md",
-         ])
+    modules = [FuzzyLogic], authors = "Luca Ferranti",
+    sitename = "FuzzyLogic.jl",
+    doctest = false, checkdocs = :exports,
+    format = Documenter.HTML(;
+        assets = [
+            DocThemeIndigo.install(FuzzyLogic),
+            "assets/favicon.ico",
+        ],
+        prettyurls = IS_CI, collapselevel = 1,
+        canonical = "https://lucaferranti.github.io/FuzzyLogic.jl"),
+    pages = [
+        "Home" => "index.md",
+        "Tutorials" => [
+            "Build a Mamdani inference system" => "tutorials/mamdani.md",
+            "Build a Sugeno inference system" => "tutorials/sugeno.md",
+            "Build a type-2 inference system" => "tutorials/type2.md",
+        ],
+        "Applications" => [
+            "Edge detection" => "applications/edge_detector.md",
+        ],
+        "API" => [
+            "Inference system API" => [
+                "Types" => "api/fis.md",
+                "Logical connectives" => "api/logical.md",
+                "Aggregation methods" => "api/aggregation.md",
+                "Defuzzification methods" => "api/defuzzification.md",
+            ],
+            "Membership functions" => "api/memberships.md",
+            "Reading/Writing" => "api/readwrite.md",
+            "Learning fuzzy models" => "api/genfis.md",
+            "Plotting" => "api/plotting.md",
+        ],
+        "Contributor's Guide" => "contributing.md",
+        "Release notes" => "changelog.md",
+    ])
 
 ##########
 # DEPLOY #
diff --git a/docs/setup.jl b/docs/setup.jl
@@ -3,7 +3,3 @@ import Pkg
 Pkg.activate(@__DIR__)
 Pkg.develop(Pkg.PackageSpec(path = joinpath(@__DIR__, "..")))
 Pkg.instantiate()
-
-# TODO remove once Documenter 0.28 is released
-# this is to get both the edit link and a the github link
-Pkg.add(Pkg.PackageSpec(name = "Documenter", rev = "30baed5"))
diff --git a/docs/src/index.md b/docs/src/index.md
