use DocumenterCitations for bibliography

JuliaReach · Jan 25, 2025 · 0b01c51 · 0b01c51
1 parent dc4078e
commit 0b01c51
Show file tree

Hide file tree

Showing 12 changed files with 144 additions and 61 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,6 +1,7 @@
 [deps]
 DisplayAs = "0b91fe84-8a4c-11e9-3e1d-67c38462b6d6"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
@@ -10,6 +11,7 @@ ReachabilityBase = "379f33d0-9447-4353-bd03-d664070e549f"
 [compat]
 DisplayAs = "0.1"
 Documenter = "1"
+DocumenterCitations = "1.3"
 Literate = "2"
 OrdinaryDiffEq = "6"
 Plots = "1"

diff --git a/docs/make.jl b/docs/make.jl
@@ -1,17 +1,20 @@
-using Documenter, ClosedLoopReachability
+using Documenter, ClosedLoopReachability, DocumenterCitations
 
 DocMeta.setdocmeta!(ClosedLoopReachability, :DocTestSetup,
                     :(using ClosedLoopReachability); recursive=true)
 
 # generate models
 include("generate.jl")
 
+bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"); style=:alpha)
+
 makedocs(; sitename="ClosedLoopReachability.jl",
          modules=[ClosedLoopReachability],
          format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true",
                                 collapselevel=1,
-                                assets=["assets/aligned.css"]),
+                                assets=["assets/aligned.css", "assets/citations.css"]),
          pagesonly=true,
+         plugins=[bib],
          pages=["Home" => "index.md",
                 "Examples" => Any[
                                   #
@@ -28,7 +31,8 @@ makedocs(; sitename="ClosedLoopReachability.jl",
                                   #
                                   ],
                 "API Reference" => Any["Problem types" => "lib/problems.md",
-                                       "Solvers" => "lib/solvers.md"]])
+                                       "Solvers" => "lib/solvers.md"],
+                "Bibliography" => "bibliography.md"])
 
 deploydocs(; repo="github.com/JuliaReach/ClosedLoopReachability.jl.git",
            push_preview=true)
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/bibliography.md b/docs/src/bibliography.md
@@ -0,0 +1,4 @@
+# Bibliography
+
+```@bibliography
+```
diff --git a/docs/src/refs.bib b/docs/src/refs.bib
@@ -0,0 +1,107 @@
+@article{TranCLMJK19,
+  author       = {Hoang{-}Dung Tran and
+                  Feiyang Cai and
+                  Diego Manzanas Lopez and
+                  Patrick Musau and
+                  Taylor T. Johnson and
+                  Xenofon D. Koutsoukos},
+  title        = {Safety Verification of Cyber-Physical Systems with Reinforcement Learning
+                  Control},
+  journal      = {Transactions on Embedded Computing Systems},
+  volume       = {18},
+  number       = {5s},
+  pages        = {105:1--105:22},
+  year         = {2019},
+  url          = {https://doi.org/10.1145/3358230},
+  doi          = {10.1145/3358230}
+}
+
+@article{PrajnaPR04,
+  author       = {Stephen Prajna and
+                  Pablo A. Parrilo and
+                  Anders Rantzer},
+  title        = {Nonlinear control synthesis by convex optimization},
+  journal      = {Transactions on Automatic Control},
+  volume       = {49},
+  number       = {2},
+  pages        = {310--314},
+  year         = {2004},
+  url          = {https://doi.org/10.1109/TAC.2003.823000},
+  doi          = {10.1109/TAC.2003.823000}
+}
+
+@techreport{Beard08,
+  title={Quadrotor dynamics and control},
+  author={Beard, Randal W},
+  institution={Brigham Young University},
+  number={1325},
+  year={2008},
+  url={https://scholarsarchive.byu.edu/facpub/1325}
+}
+
+@inproceedings{RavaioliCMGDH22,
+  title={Safe reinforcement learning benchmark environments for aerospace control systems},
+  author={Ravaioli, Umberto J and Cunningham, James and McCarroll, John and Gangal, Vardaan and Dunlap, Kyle and Hobbs, Kerianne L},
+  booktitle={Aerospace Conference ({AERO})},
+  pages={1--20},
+  year={2022},
+  organization={IEEE}
+}
+
+@article{JankovicFK96,
+  author       = {Mrdjan Jankovic and
+                  Daniel Fontaine and
+                  Petar V. Kokotovic},
+  title        = {{TORA} example: cascade- and passivity-based control designs},
+  journal      = {Transactions on Control Systems Technology},
+  volume       = {4},
+  number       = {3},
+  pages        = {292--297},
+  year         = {1996},
+  url          = {https://doi.org/10.1109/87.491203},
+  doi          = {10.1109/87.491203}
+}
+
+@inproceedings{AlthoffKM17,
+  author       = {Matthias Althoff and
+                  Markus Koschi and
+                  Stefanie Manzinger},
+  title        = {{CommonRoad}: Composable benchmarks for motion planning on roads},
+  booktitle    = {Intelligent Vehicles ({IV})},
+  pages        = {719--726},
+  publisher    = {{IEEE}},
+  year         = {2017},
+  url          = {https://doi.org/10.1109/IVS.2017.7995802},
+  doi          = {10.1109/IVS.2017.7995802}
+}
+
+@article{JulianK19,
+  author       = {Kyle D. Julian and
+                  Mykel J. Kochenderfer},
+  title        = {A Reachability Method for Verifying Dynamical Systems with Deep Neural
+                  Network Controllers},
+  journal      = {CoRR},
+  volume       = {abs/1903.00520},
+  year         = {2019},
+  url          = {http://arxiv.org/abs/1903.00520},
+  eprinttype    = {arXiv},
+  eprint       = {1903.00520}
+}
+
+@inproceedings{AkintundeBKL20,
+  author       = {Michael E. Akintunde and
+                  Elena Botoeva and
+                  Panagiotis Kouvaros and
+                  Alessio Lomuscio},
+  editor       = {Amal El Fallah Seghrouchni and
+                  Gita Sukthankar and
+                  Bo An and
+                  Neil Yorke{-}Smith},
+  title        = {Formal Verification of Neural Agents in Non-deterministic Environments},
+  booktitle    = {Autonomous Agents and Multiagent Systems ({AAMAS})},
+  pages        = {25--33},
+  publisher    = {IFAAMAS},
+  year         = {2020},
+  url          = {http://ifaamas.org/Proceedings/aamas2020/pdfs/p25.pdf},
+  doi          = {10.5555/3398761.3398770}
+}
diff --git a/models/ACC/ACC.jl b/models/ACC/ACC.jl
@@ -2,7 +2,7 @@
 #
 # The Adaptive Cruise Control (ACC) benchmark models a car that drives at a set
 # velocity and maintains a safe distance from a lead car by adjusting the
-# longitudinal acceleration [^TCMMJK].
+# longitudinal acceleration [TranCLMJK19](@cite).
 #
 # ![](ACC_explanation.png)
 
@@ -258,11 +258,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig))
 
 end  #jl
 nothing  #jl
-
-# ## References
-
-# [^TCMMJK]: Hoang-Dung Tran, Feiyang Cai, Diego Manzanas Lopez, Patrick Musau,
-#            Taylor T. Johnson, and Xenofon D. Koutsoukos (2019). *Safety
-#            verification of cyber-physical systems with reinforcement learning
-#            control*. In
-#            [ACM Trans. Embed. Comput. Syst.](https://doi.org/10.1145/3358230)
diff --git a/models/AttitudeControl/AttitudeControl.jl b/models/AttitudeControl/AttitudeControl.jl
@@ -1,6 +1,6 @@
 # # Attitude Control
 #
-# The Attitude Control benchmark models a rigid-body system [^PPR].
+# The Attitude Control benchmark models a rigid-body system [PrajnaPR04](@cite).
 
 module AttitudeControl  #jl
 
@@ -165,9 +165,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig))
 
 end  #jl
 nothing  #jl
-
-# ## References
-
-# [^PPR]: Stephen Prajna, Pablo A. Parrilo, and Anders Rantzer (2004).
-#         *Nonlinear control synthesis by convex optimization*. In
-#         [IEEE Trans. Autom. Control](https://doi.org/10.1109/TAC.2003.823000).
diff --git a/models/Quadrotor/Quadrotor.jl b/models/Quadrotor/Quadrotor.jl
@@ -21,7 +21,7 @@ using Plots: plot, plot!
 # ``(x_7, x_8, x_9)`` is the (roll, pitch, yaw) angle, and
 # ``(x_{10}, x_{11}, x_{12})`` is the (roll, pitch, yaw) rate. The control
 # inputs ``(u_1, u_2, u_3)`` represent the torque. For more details we refer to
-# [^B].
+# [Beard08](@citet).
 
 vars_idx = Dict(:states => 1:12, :controls => 13:15)
 
@@ -192,8 +192,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig))
 
 end  #jl
 nothing  #jl
-
-# ## References
-
-# [^B]: Randal Beard (2008). *Quadrotor dynamics and control*.
-#       [Technical report](https://scholarsarchive.byu.edu/facpub/1325/).
diff --git a/models/SpacecraftDocking/SpacecraftDocking.jl b/models/SpacecraftDocking/SpacecraftDocking.jl
@@ -16,7 +16,7 @@ using Plots: plot, plot!
 
 # There are 4 state variables ``(s_x, s_y, \dot{s}_x, \dot{s}_y)``, where
 # ``(s_x, s_y)`` is the position and ``(\dot{s}_x, \dot{s}_y)`` is the velocity
-# of the spacecraft [^RCMGDH].
+# of the spacecraft [RavaioliCMGDH22](@cite).
 
 vars_idx = Dict(:states => 1:4, :controls => 5:6)
 
@@ -161,11 +161,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig))
 
 end  #jl
 nothing  #jl
-
-# ## References
-
-# [^RCMGDH]: Umberto J. Ravaioli, James Cunningham, John McCarroll, Vardaan
-#            Gangal, Kyle Dunlap, and Kerianne L. Hobbs (2022). *Safe
-#            reinforcement learning benchmark environments for aerospace control
-#            systems*. In
-#            [IEEE Aerospace Conference](https://doi.org/10.1109/AERO53065.2022.9843750).
diff --git a/models/TORA/TORA.jl b/models/TORA/TORA.jl
@@ -3,7 +3,7 @@
 # The TORA benchmark models a cart attached to a wall with a spring. The cart is
 # free to move on a friction-less surface and has a weight attached to an arm,
 # which is free to rotate about an axis. This serves as the control input to
-# stabilize the cart at the origin ``x = 0`` [^JFK].
+# stabilize the cart at the origin ``x = 0`` [JankovicFK96](@cite).
 #
 # ![](TORA_explanation.png)
 #
@@ -320,9 +320,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig))
 
 end  #jl
 nothing  #jl
-
-# ## References
-
-# [^JFK]: Mrdjan Jankovic, Daniel Fontaine, and Petar V. Kokotovic. *TORA
-#         example: cascade- and passivity-based control designs*. In
-#         [IEEE Trans. Control. Syst. Technol.](https://doi.org/10.1109/87.491203)
diff --git a/models/Unicycle/Unicycle.jl b/models/Unicycle/Unicycle.jl
@@ -1,6 +1,6 @@
 # # Unicycle
 #
-# The Unicycle benchmark models a unicycle vehicle [^AKM].
+# The Unicycle benchmark models a unicycle vehicle [AlthoffKM17](@cite).
 #
 # ![](Unicycle_explanation.png)
 
@@ -202,9 +202,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig))
 
 end  #jl
 nothing  #jl
-
-# ## References
-
-# [^AKM]: Matthias Althoff, Markus Koschi, and Stefanie Manzinger (2017).
-#         *CommonRoad: Composable benchmarks for motion planning on roads.* In
-#         [IEEE Intelligent Vehicles Symposium](https://doi.org/10.1109/IVS.2017.7995802).
diff --git a/models/VerticalCAS/VerticalCAS.jl b/models/VerticalCAS/VerticalCAS.jl
@@ -2,7 +2,7 @@
 #
 # The VerticalCAS benchmark considers a collision avoidance system (CAS),
 # required for commercial aircraft, which gives vertical climbrate advisories
-# to pilots [^JK][^ABKL].
+# to pilots [JulianK19, AkintundeBKL20](@cite).
 
 module VerticalCAS  #jl
 
@@ -371,15 +371,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig))
 
 end  #jl
 nothing  #jl
-
-# ## References
-
-# [^JK]: Kyle D. Julian and Mykel J. Kochenderfer (2019). *A reachability method
-#        for verifying dynamical systems with deep neural network controllers*.
-#        [arXiv:1903.00520](https://arxiv.org/pdf/1903.00520.pdf).
-#
-# [^ABKL]: Michael E. Akintunde, Elena Botoeva, Panagiotis Kouvaros, and Alessio
-#          Lomuscio (2020). *Formal verification of neural agents in
-#          non-deterministic environments*. In [Proceedings of the 19th
-#          International Conference on Autonomous Agents and Multiagent
-#          Systems](http://ifaamas.org/Proceedings/aamas2020/pdfs/p25.pdf).