Merge pull request #287 from SciML/fm/docs

docs: uniform citations in docs with DocumenterCitations

Author: MartinuzziFrancesco

Project.toml

@@ -1,7 +1,7 @@
 name = "ReservoirComputing"
 uuid = "7c2d2b1e-3dd4-11ea-355a-8f6a8116e294"
 authors = ["Francesco Martinuzzi"]
-version = "0.11.2"
+version = "0.11.3"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"

README.md

@@ -27,6 +27,38 @@ Use the
 [in-development documentation](https://docs.sciml.ai/ReservoirComputing/dev/)
 to take a look at not yet released features.
 
+## Citing
+
+If you use this library in your work, please cite:
+
+```bibtex
+@article{martinuzzi2022reservoircomputing,
+  author  = {Francesco Martinuzzi and Chris Rackauckas and Anas Abdelrehim and Miguel D. Mahecha and Karin Mora},
+  title   = {ReservoirComputing.jl: An Efficient and Modular Library for Reservoir Computing Models},
+  journal = {Journal of Machine Learning Research},
+  year    = {2022},
+  volume  = {23},
+  number  = {288},
+  pages   = {1--8},
+  url     = {http://jmlr.org/papers/v23/22-0611.html}
+}
+```
+
+## Installation
+
+ReservoirComputing.jl can be installed using either of
+
+```julia_repl
+julia> ] #actually press the closing square brackets
+pkg> add ReservoirComputing
+```
+or
+
+```julia
+using Pkg
+Pkg.add("ReservoirComputing")
+```
+
 ## Quick Example
 
 To illustrate the workflow of this library we will showcase
@@ -36,7 +68,9 @@ For the `Generative` prediction we need the target data
 to be one step ahead of the training data:
 
 ```julia
-using ReservoirComputing, OrdinaryDiffEq
+using ReservoirComputing, OrdinaryDiffEq, Random
+Random.seed!(42)
+rng = MersenneTwister(17)
 
 #lorenz system parameters
 u0 = [1.0, 0.0, 0.0]
@@ -74,7 +108,8 @@ res_size = 300
 esn = ESN(input_data, input_size, res_size;
     reservoir=rand_sparse(; radius=1.2, sparsity=6 / res_size),
     input_layer=weighted_init,
-    nla_type=NLAT2())
+    nla_type=NLAT2(),
+    rng=rng)
 ```
 
 The echo state network can now be trained and tested.
@@ -110,23 +145,6 @@ plot!(transpose(test)[:, 1], transpose(test)[:, 2], transpose(test)[:, 3]; label
 
 ![lorenz_attractor](https://user-images.githubusercontent.com/10376688/81470281-5a34b580-91ea-11ea-9eea-d2b266da19f4.png)
 
-## Citing
-
-If you use this library in your work, please cite:
-
-```bibtex
-@article{JMLR:v23:22-0611,
-  author  = {Francesco Martinuzzi and Chris Rackauckas and Anas Abdelrehim and Miguel D. Mahecha and Karin Mora},
-  title   = {ReservoirComputing.jl: An Efficient and Modular Library for Reservoir Computing Models},
-  journal = {Journal of Machine Learning Research},
-  year    = {2022},
-  volume  = {23},
-  number  = {288},
-  pages   = {1--8},
-  url     = {http://jmlr.org/papers/v23/22-0611.html}
-}
-```
-
 ## Acknowledgements
 
 This project was possible thanks to initial funding through

docs/Project.toml

@@ -2,6 +2,7 @@
 CellularAutomata = "878138dc-5b27-11ea-1a71-cb95d38d6b29"
 DifferentialEquations = "0c46a032-eb83-5123-abaf-570d42b7fbaa"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"

docs/make.jl

@@ -1,4 +1,4 @@
-using Documenter, ReservoirComputing
+using Documenter, DocumenterCitations, ReservoirComputing
 
 cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml"; force = true)
 cp("./docs/Project.toml", "./docs/src/assets/Project.toml"; force = true)
@@ -8,9 +8,15 @@ ENV["GKSwstype"] = "100"
 include("pages.jl")
 mathengine = Documenter.MathJax()
 
+bib = CitationBibliography(
+    joinpath(@__DIR__, "src", "refs.bib");
+    style = :authoryear
+)
+
 makedocs(; modules = [ReservoirComputing],
     sitename = "ReservoirComputing.jl",
     clean = true, doctest = false, linkcheck = true,
+    plugins = [bib],
     format = Documenter.HTML(;
         mathengine,
         assets = ["assets/favicon.ico"],

docs/pages.jl

@@ -20,5 +20,5 @@ pages = [
         "ESN Initializers" => "api/inits.md",
         "ESN Drivers" => "api/esn_drivers.md",
         "ESN Variations" => "api/esn_variations.md",
-        "ReCA" => "api/reca.md"]
+        "ReCA" => "api/reca.md"]    #"References" => "references.md"
 ]

docs/src/api/esn_drivers.md

@@ -14,3 +14,10 @@ The `GRU` driver also provides the user with the choice of the possible variants
 ```
 
 Please refer to the original papers for more detail about these architectures.
+
+## References
+
+```@bibliography
+Pages = ["esn_drivers.md"]
+Canonical = false
+```

docs/src/api/inits.md

@@ -44,3 +44,10 @@
     self_loop!
     add_jumps!
 ```
+
+## References
+
+```@bibliography
+Pages = ["inits.md"]
+Canonical = false
+```

docs/src/api/states.md

@@ -25,3 +25,10 @@
 ```@docs
     ReservoirComputing.create_states
 ```
+
+## References
+
+```@bibliography
+Pages = ["states.md"]
+Canonical = false
+```

docs/src/esn_tutorials/change_layers.md

@@ -26,7 +26,7 @@ Custom layers only need to follow these APIs to be compatible with ReservoirComp
 
 ## Example of minimally complex ESN
 
-Using [^rodan2012] and [^rodan2010] as references this section will provide an
+Using [Rodan2012](@cite) and [Rodan2011](@cite) as references this section will provide an
 example on how to change both the input layer and the reservoir for ESNs.
 
 The task for this example will be the one step ahead prediction of the Henon map.
@@ -77,11 +77,9 @@ end
 As it is possible to see, changing layers in ESN models is straightforward.
 Be sure to check the API documentation for a full list of reservoir and layers.
 
-## Bibliography
+## References
 
-[^rodan2012]: Rodan, Ali, and Peter Tiňo.
-    “Simple deterministically constructed cycle reservoirs with regular jumps.”
-    Neural computation 24.7 (2012): 1822-1852.
-[^rodan2010]: Rodan, Ali, and Peter Tiňo.
-    “Minimum complexity echo state network.”
-    IEEE transactions on neural networks 22.1 (2010): 131-144.
+```@bibliography
+Pages = ["change_layers.md"]
+Canonical = false
+```

docs/src/esn_tutorials/deep_esn.md

@@ -2,7 +2,7 @@
 
 Deep Echo State Network architectures started to gain some traction recently. In this guide, we illustrate how it is possible to use ReservoirComputing.jl to build a deep ESN.
 
-The network implemented in this library is taken from [^1]. It works by stacking reservoirs on top of each other, feeding the output from one into the next. The states are obtained by merging all the inner states of the stacked reservoirs. For a more in-depth explanation, refer to the paper linked above.
+The network implemented in this library is taken from [Gallicchio2017](@cite). It works by stacking reservoirs on top of each other, feeding the output from one into the next. The states are obtained by merging all the inner states of the stacked reservoirs. For a more in-depth explanation, refer to the paper linked above.
 
 ## Lorenz Example
 
@@ -88,6 +88,9 @@ plot(p1, p2, p3; plot_title="Lorenz System Coordinates",
     legendfontsize=12, titlefontsize=20)
 ```
 
-## Documentation
+## References
 
-[^1]: Gallicchio, Claudio, and Alessio Micheli. "_Deep echo state network (deepesn): A brief survey._" arXiv preprint arXiv:1712.04323 (2017).
+```@bibliography
+Pages = ["deep_esn.md"]
+Canonical = false
+```