[docs] add DocumenterCitations (#3596)

* [POC] BibTeX -> cite with DocumenterCitations * fix format * Fix * Add Knuth * Update make.jl * Update documentation.yml * Update * Update docs/make.jl * Apply suggestions from code review * Try with accents --------- Co-authored-by: Oscar Dowson <[email protected]> Co-authored-by: odow <[email protected]>
jump-dev · Dec 8, 2023 · 60dc624 · 60dc624
1 parent 280f5fb
commit 60dc624
Show file tree

Hide file tree

Showing 6 changed files with 108 additions and 33 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -6,6 +6,7 @@ DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DimensionalData = "0703355e-b756-11e9-17c0-8b28908087d0"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 Dualization = "191a621a-6537-11e9-281d-650236a99e60"
 GLPK = "60bf3e95-4087-53dc-ae20-288a0d20c6a6"
@@ -41,6 +42,7 @@ DataFrames = "1"
 DimensionalData = "0.24"
 Distributions = "0.25"
 Documenter = "=1.1.2"
+DocumenterCitations = "1"
 Dualization = "0.5"
 GLPK = "=1.1.3"
 HTTP = "1.5.4"

diff --git a/docs/make.jl b/docs/make.jl
@@ -4,6 +4,7 @@
 #  file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 import Documenter
+import DocumenterCitations
 import Downloads
 import Literate
 import MathOptInterface
@@ -359,8 +360,10 @@ const _PAGES = [
         "manual/nlp.md",
     ],
     jump_api_reference,
-    "Background Information" =>
-        ["background/algebraic_modeling_languages.md"],
+    "Background Information" => [
+        "background/algebraic_modeling_languages.md",
+        "background/bibliography.md",
+    ],
     "Developer Docs" => [
         "Contributing" => "developers/contributing.md",
         "Extensions" => "developers/extensions.md",
@@ -558,7 +561,7 @@ remotes = Dict(pkgdir(MOI) => (gh_moi, version))
         analytics = "UA-44252521-1",
         mathengine = Documenter.MathJax2(),
         collapselevel = 1,
-        assets = ["assets/extra_styles.css"],
+        assets = ["assets/extra_styles.css", "assets/citations.css"],
         sidebar_sitename = false,
         # Do no check for large pages.
         size_threshold_ignore = [
@@ -581,6 +584,12 @@ remotes = Dict(pkgdir(MOI) => (gh_moi, version))
     doctest = _FIX ? :fix : !_FAST,
     pages = vcat(_PAGES, "release_notes.md"),
     remotes = remotes,
+    plugins = [
+        DocumenterCitations.CitationBibliography(
+            joinpath(@__DIR__, "src", "references.bib");
+            style = :authoryear,
+        ),
+    ],
 )
 
 # ==============================================================================
@@ -623,6 +632,12 @@ if _PDF
         build = "latex_build",
         pages = _PAGES,
         debug = true,
+        plugins = [
+            DocumenterCitations.CitationBibliography(
+                joinpath(@__DIR__, "src", "references.bib");
+                style = :authoryear,
+            ),
+        ],
     )
     # Hack for deploying: copy the pdf (and only the PDF) into the HTML build
     # directory! We don't want to copy everything in `latex_build` because it

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;}
+.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/background/bibliography.md b/docs/src/background/bibliography.md
@@ -0,0 +1,4 @@
+# Bibliography
+
+```@bibliography
+```
diff --git a/docs/src/references.bib b/docs/src/references.bib
@@ -0,0 +1,56 @@
+@Book{Barvinok2002,
+  author    = {Barvinok, Alexander},
+  title     = {A course in convexity},
+  publisher = {American Mathematical Society},
+  series    = {Graduate studies in mathematics},
+  year      = {2002},
+  volume    = {54},
+  doi       = {https://doi.org/10.1090/gsm/054},
+}
+
+@Article{Bertsimas2018,
+  author  = {Bertsimas, Dimitris and Gupta, Vishal and Kallus, Nathan},
+  journal = {Mathematical Programming},
+  title   = {Data-driven robust optimization},
+  year    = {2018},
+  issn    = {1436-4646},
+  number  = {2},
+  pages   = {235--292},
+  volume  = {167},
+  doi     = {10.1007/s10107-017-1125-8},
+}
+
+@Article{Knuth1994,
+  author  = {Knuth, Donald E.},
+  title   = {The sandwich theorem},
+  journal = {The Electronic Journal of Combinatorics},
+  volume  = {1},
+  year    = {1994},
+  doi     = {10.37236/1193},
+}
+
+@InProceedings{Linial2002,
+  author    = {Linial, Nathan},
+  title     = {Finite Metric Spaces: Combinatorics, Geometry and Algorithms},
+  year      = {2002},
+  address   = {New York, NY, USA},
+  pages     = {63},
+  publisher = {Association for Computing Machinery},
+  series    = {SCG '02},
+  doi       = {10.1145/513400.513441},
+  isbn      = {1581135041},
+  location  = {Barcelona, Spain},
+  numpages  = {1},
+}
+
+@Book{Matousek2013,
+  author    = {Matou{\v{s}}ek, Jiri},
+  publisher = {Springer Science \& Business Media},
+  title     = {Lectures on discrete geometry},
+  year      = {2013},
+  isbn      = {978-1-4613-0039-7},
+  number    = {1},
+  series    = {Graduate Texts in Mathematics},
+  volume    = {212},
+  doi       = {10.1007/978-1-4613-0039-7},
+}
diff --git a/docs/src/tutorials/conic/simple_examples.jl b/docs/src/tutorials/conic/simple_examples.jl
@@ -32,7 +32,7 @@ import Test
 # where ``L`` is the weighted graph Laplacian and ``e`` is a vector of ones.
 # For more details, see:
 #
-# Goemans, M. X., & Williamson, D. P. (1995). 
+# Goemans, M. X., & Williamson, D. P. (1995).
 # [_Improved approximation algorithms for maximum cut and satisfiability problems
 # using semidefinite programming._](https://doi.org/10.1145/227683.227684)
 # Journal of the ACM (JACM), 42(6), 1115-1145.
@@ -122,7 +122,7 @@ S, T = solve_max_cut_sdp([0 1 5 0; 1 0 0 9; 5 0 0 2; 0 9 2 0])
 # Given a set of points ``a_1, \ldots, a_m``  in ``\mathbb{R}^n``, allocate them to ``k`` clusters.
 #
 # For more details, see:
-# 
+#
 # Peng, J., & Wei, Y. (2007).
 # [_Approximating k-means-type clustering via semidefinite programming_](https://doi.org/10.1137/050641983).
 # SIAM Journal on Optimization, 18(1), 186-205.
@@ -179,7 +179,7 @@ example_k_means_clustering()
 # \begin{bmatrix}
 #       1   &  ρ_{AB} &  ρ_{AC} \\
 #      ρ_{AB} &  1    &  ρ_{BC}  \\
-#      ρ_{AC} &  ρ_{BC} &  1   
+#      ρ_{AC} &  ρ_{BC} &  1
 # \end{bmatrix} \succeq 0
 # ```
 
@@ -250,18 +250,11 @@ example_correlation_problem()
 # ```math
 #     D[a, b]^2 \leq Q[a, a] + Q[b, b] - 2 Q[a, b] \leq c^2 \; D[a, b]^2
 # ```
-# for all edges ``(a, b)`` in the graph and minimize ``c^2``, 
+# for all edges ``(a, b)`` in the graph and minimize ``c^2``,
 # which gives us the SDP formulation below.
 # Since we may choose any point to be the origin, we fix the first vertex at 0.
 #
-# For more details, see:
-#
-# J. Matoušek (2002), [_Lectures on discrete geometry_](https://doi.org/10.1007/978-1-4613-0039-7),
-# Springer, pp. 378-379
-# 
-#  N. Linial (2002), 
-# _[Finite metric spaces--combinatorics, geometry and algorithms](https://arxiv.org/abs/math/0304466)_,
-# Proceedings of the ICM, Vol. 3, 573-586
+# For more details, see [Matousek2013,Linial2002](@cite).
 
 function example_minimum_distortion()
     model = Model(SCS.Optimizer)
@@ -318,11 +311,11 @@ example_minimum_distortion()
 # Consider the pentagon graph:
 # ```raw
 #      [5]
-#     /   \    
-#    /     \     
+#     /   \
+#    /     \
 #  [1]     [4]
 #   |       |
-#   |       |  
+#   |       |
 #  [2] --- [3]
 # ```
 # with five vertices and edges. Its Lovász number is known to be precisely
@@ -334,7 +327,7 @@ example_minimum_distortion()
 # matrix with entries ``(i,j)`` and ``(j,i)`` equal to 1, with all other entries 0.
 # Let  ``E`` be the graph's edge set; in this example, ``E`` contains
 # (1,2), (2,3), (3,4), (4,5), (5,1)
-# and their transposes. The Lovász number can be computed from the program 
+# and their transposes. The Lovász number can be computed from the program
 # ```math
 # \begin{align}
 #     \text{max}      & \quad    J • X & \\
@@ -345,15 +338,7 @@ example_minimum_distortion()
 # ```
 # where ``J`` is the matrix filled with ones, and ``I`` is the identity matrix.
 #
-# For more details, see:
-#
-# Barvinok, A. (2002).
-# A course in convexity,
-# American Mathematical Society (Vol. 54), pp. 182-185.
-#
-# Knuth, D. E. (1994), 
-# [_The sandwich theorem_](https://doi.org/10.37236%2F1193), 
-# Electronic Journal of Combinatorics, Volume 1, Issue 1, A1.
+# For more details, see [Barvinok2002,Knuth1994](@cite).
 
 function example_theta_problem()
     model = Model(SCS.Optimizer)
@@ -387,11 +372,7 @@ example_theta_problem()
 
 # This example computes the Value at Risk for a data-driven uncertainty set.
 # Closed-form expressions for the optimal value are available.
-# For more details, see:
-
-# Bertsimas, D., Gupta, V., & Kallus, N. (2018). 
-# [_Data-driven robust optimization._](https://doi.org/10.1007/s10107-017-1125-8)
-# Mathematical Programming, 167, 235-292.
+# For more details, see [Bertsimas2018](@cite).
 
 function example_robust_uncertainty_sets()
     R, d, 𝛿, ɛ = 1, 3, 0.05, 0.05