[docs] add DocumenterCitations (#336)

* [docs] add DocumenterCitations * Add Floudas * Fixes * Add missing files * Fix
jump-dev · Dec 7, 2023 · 36c7849 · 36c7849
1 parent 2efff04
commit 36c7849
Show file tree

Hide file tree

Showing 13 changed files with 83 additions and 65 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -7,6 +7,7 @@ Cyclotomics = "da8f5974-afbb-4dc8-91d8-516d5257c83b"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 DifferentialEquations = "0c46a032-eb83-5123-abaf-570d42b7fbaa"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 Dualization = "191a621a-6537-11e9-281d-650236a99e60"
 DynamicPolynomials = "7c1d4256-1411-5781-91ec-d7bc3513ac07"
 GroupsCore = "d5909c97-4eac-4ecc-a3dc-fdd0858a4120"

diff --git a/docs/make.jl b/docs/make.jl
@@ -2,6 +2,7 @@
 
 using SumOfSquares
 using Documenter, Literate
+import DocumenterCitations
 
 const _TUTORIAL_DIR = joinpath(@__DIR__, "src", "tutorials")
 const _OUTPUT_DIR   = joinpath(@__DIR__, "src", "generated")
@@ -34,7 +35,10 @@ literate_directory.(_TUTORIAL_SUBDIR)
 makedocs(
     sitename = "SumOfSquares",
     # See https://github.com/JuliaDocs/Documenter.jl/issues/868
-    format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
+    format = Documenter.HTML(
+        prettyurls = get(ENV, "CI", nothing) == "true",
+        assets = ["assets/citations.css"],
+    ),
     pages = [
         "Index" => "index.md",
         "Sum-of-Squares Programming" => "sumofsquares.md",
@@ -51,10 +55,17 @@ makedocs(
                 ),
             _TUTORIAL_SUBDIR,
         ),
+        "Bibliography" => "bibliography.md",
     ],
     # The following ensures that we only include the docstrings from
     # this module for functions define in Base that we overwrite.
-    modules = [SumOfSquares, PolyJuMP]
+    modules = [SumOfSquares, PolyJuMP],
+    plugins = [
+        DocumenterCitations.CitationBibliography(
+            joinpath(@__DIR__, "src", "references.bib");
+            style = :authoryear,
+        ),
+    ],
 )
 
 deploydocs(

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/bibliography.md b/docs/src/bibliography.md
@@ -0,0 +1,4 @@
+# Bibliography
+
+```@bibliography
+```
diff --git a/docs/src/references.bib b/docs/src/references.bib
@@ -0,0 +1,37 @@
+ 
+@Book{Floudas1999,
+  author    = {Floudas, Christodoulos A. and Pardalos, Pãnos M. and Adjiman, Claire S. and Esposito, William R. and Gümüş, Zeynep H. and Harding, Stephen T. and Klepeis, John L. and Meyer, Clifford A. and Schweiger, Carl A.},
+  publisher = {Springer US},
+  title     = {Handbook of Test Problems in Local and Global Optimization},
+  year      = {1999},
+  isbn      = {9781475730401},
+  doi       = {10.1007/978-1-4757-3040-1},
+  issn      = {1571-568X},
+  journal   = {Nonconvex Optimization and Its Applications},
+}
+
+@Book{Lasserre2009,
+  author    = {Lasserre, Jean Bernard},
+  publisher = {Imperial College Press},
+  title     = {Moments, Positive Polynomials and Their Applications},
+  year      = {2009},
+  isbn      = {9781848164468},
+  month     = oct,
+  doi       = {10.1142/p665},
+  file      = {:ebooks/Lasserre_2009_Moments, positive polynomials and their applications.pdf:PDF},
+  issn      = {2399-1593},
+  journal   = {Series on Optimization and Its Applications},
+}
+
+@InBook{Laurent2008,
+  author    = {Laurent, Monique},
+  pages     = {157--270},
+  publisher = {Springer New York},
+  title     = {Sums of Squares, Moment Matrices and Optimization Over Polynomials},
+  year      = {2008},
+  isbn      = {9780387096865},
+  month     = sep,
+  booktitle = {The IMA Volumes in Mathematics and its Applications},
+  doi       = {10.1007/978-0-387-09686-5_7},
+  issn      = {0940-6573},
+}
diff --git a/docs/src/sumofsquares.md b/docs/src/sumofsquares.md
@@ -52,10 +52,6 @@ These facts can be verified numerically using this package as detailed in the [m
 *Semidefinite Optimization and Convex Algebraic Geometry*.
 Society for Industrial and Applied Mathematics, **2012**.
 
-[Las09] Lasserre, J. B.
-*Moments, positive polynomials and their applications*
-World Scientific, **2009**.
-
 [Lau09] Laurent, M.
 *Sums of squares, moment matrices and optimization over polynomials*
 Emerging applications of algebraic geometry, Springer, **2009**, 157-270.
diff --git a/docs/src/tutorials/Extension/certificate.jl b/docs/src/tutorials/Extension/certificate.jl
@@ -6,14 +6,10 @@
 
 # ## Introduction
 
-# Consider the polynomial optimization problem (a variation from [L09, Example 2.2]) of
+# Consider the polynomial optimization problem (a variation from [Lasserre2009; Example 2.2](@cite)) of
 # minimizing the polynomial $x^3 - x^2 + 2xy - y^2 + y^3$
 # over the polyhedron defined by the inequalities $x \ge 0, y \ge 0$ and $x + y \geq 1$.
 
-# [L09] Lasserre, J. B.
-# *Moments, positive polynomials and their applications*.
-# World Scientific, **2009**.
-
 using Test #src
 using DynamicPolynomials
 @polyvar x y

diff --git a/docs/src/tutorials/Polynomial Optimization/bilinear.jl b/docs/src/tutorials/Polynomial Optimization/bilinear.jl
@@ -2,19 +2,11 @@
 
 #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/generated/Polynomial Optimization/bilinear.ipynb)
 #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/generated/Polynomial Optimization/bilinear.ipynb)
-# **Adapted from**: Section 3.1 of [F99] and Table 5.1 of [Las09]
-#
-# [F99] Floudas, Christodoulos A. et al.
-# *Handbook of Test Problems in Local and Global Optimization.*
-# Nonconvex Optimization and Its Applications (NOIA, volume 33).
-#
-# [Las09] Lasserre, J. B.
-# *Moments, positive polynomials and their applications*
-# World Scientific, **2009**.
+# **Adapted from**: [Floudas1999; Section 3.1](@cite) and [Lasserre2009; Table 5.1](@cite)
 
 # ## Introduction
 
-# Consider the polynomial optimization problem [F99, Section 3.1]
+# Consider the polynomial optimization problem from [Floudas1999; Section 3.1](@cite).
 
 using Test #src
 using DynamicPolynomials

diff --git a/docs/src/tutorials/Polynomial Optimization/ellipsoid.jl b/docs/src/tutorials/Polynomial Optimization/ellipsoid.jl
@@ -2,19 +2,11 @@
 
 #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/generated/Polynomial Optimization/ellipsoid.ipynb)
 #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/generated/Polynomial Optimization/ellipsoid.ipynb)
-# **Adapted from**: Section 3.5 of [F99] and Table 5.1 of [Las09]
-#
-# [F99] Floudas, Christodoulos A. et al.
-# *Handbook of Test Problems in Local and Global Optimization.*
-# Nonconvex Optimization and Its Applications (NOIA, volume 33).
-#
-# [Las09] Lasserre, J. B.
-# *Moments, positive polynomials and their applications*
-# World Scientific, **2009**.
+# **Adapted from**: [Floudas1999; Section 3.5](@cite) and [Lasserre2009; Table 5.1](@cite)
 
 # ## Introduction
 
-# Consider the polynomial optimization problem [F99, Section 3.5]
+# Consider the polynomial optimization problem from [Floudas1999; Section 3.5](@cite)
 
 A = [
      0  0  1

diff --git a/docs/src/tutorials/Polynomial Optimization/goldstein_price.jl b/docs/src/tutorials/Polynomial Optimization/goldstein_price.jl
@@ -47,11 +47,7 @@ solution_summary(model)
 # The moment matrix is as follows, we can already see the global minimizer
 # `[0, -1]` from the entries `(2, 1)` and `(3, 1)`.
 # This heuristic way to obtain solutions to the polynomial optimization problem
-# is suggested in [L09, (6.15)].
-#
-# [L09] Laurent, Monique.
-# *Sums of squares, moment matrices and optimization over polynomials.*
-# Emerging applications of algebraic geometry (2009): 157-270.
+# is suggested in [Laurent2008; (6.15)](@cite).
 
 ν = moment_matrix(con_ref)
 

diff --git a/docs/src/tutorials/Polynomial Optimization/min_univariate.jl b/docs/src/tutorials/Polynomial Optimization/min_univariate.jl
@@ -2,23 +2,11 @@
 
 #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/generated/Polynomial Optimization/min_univariate.ipynb)
 #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/generated/Polynomial Optimization/min_univariate.ipynb)
-# **Adapted from**: Section 4.10 of [F99], Example 6.23 of [L09] and Table 5.1 of [Las09]
-#
-# [F99] Floudas, Christodoulos A. et al.
-# *Handbook of Test Problems in Local and Global Optimization.*
-# Nonconvex Optimization and Its Applications (NOIA, volume 33).
-#
-# [L09] Laurent, Monique.
-# *Sums of squares, moment matrices and optimization over polynomials.*
-# Emerging applications of algebraic geometry (2009): 157-270.
-#
-# [Las09] Lasserre, J. B.
-# *Moments, positive polynomials and their applications*
-# World Scientific, **2009**.
+# **Adapted from**: [Floudas1999; Section 4.10](@cite), [Laurent2008; Example 6.23](@cite) and [Lasserre2009; Table 5.1](@cite)
 
 # ## Introduction
 
-# Consider the polynomial optimization problem [F99, Section 4.10]
+# Consider the polynomial optimization problem from [Floudas1999; Section 4.10](@cite)
 # of minimizing the linear function $-x_1 - x_2$
 # over the basic semialgebraic set defined by the inequalities
 # $x_2 \le 2x_1^4 - 8x_1^3 + 8x_1^2 + 2$,

diff --git a/docs/src/tutorials/Polynomial Optimization/polynomial_optimization.jl b/docs/src/tutorials/Polynomial Optimization/polynomial_optimization.jl
@@ -6,14 +6,10 @@
 
 # ## Introduction
 
-# Consider the polynomial optimization problem [L09, Example 2.2] of
+# Consider the polynomial optimization problem [Lasserre2009; Example 2.2](@cite) of
 # minimizing the polynomial $x^3 - x^2 + 2xy - y^2 + y^3$
 # over the polyhedron defined by the inequalities $x \ge 0, y \ge 0$ and $x + y \geq 1$.
 
-# [L09] Lasserre, J. B.
-# *Moments, positive polynomials and their applications*.
-# World Scientific, **2009**.
-
 using Test #src
 using DynamicPolynomials
 @polyvar x y

diff --git a/docs/src/tutorials/Polynomial Optimization/qp.jl b/docs/src/tutorials/Polynomial Optimization/qp.jl
@@ -2,19 +2,11 @@
 
 #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/generated/Polynomial Optimization/qp.ipynb)
 #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/generated/Polynomial Optimization/qp.ipynb)
-# **Adapted from**: Section 2.2 of [F99], Table 5.1 of [Las09]
-#
-# [F99] Floudas, Christodoulos A. et al.
-# *Handbook of Test Problems in Local and Global Optimization.*
-# Nonconvex Optimization and Its Applications (NOIA, volume 33).
-#
-# [Las09] Lasserre, J. B.
-# *Moments, positive polynomials and their applications*
-# World Scientific, **2009**.
+# **Adapted from**:  of [Floudas1999; Section 2.2](@cite), [Lasserre2009; Table 5.1](@cite)
 
 # ## Introduction
 
-# Consider the nonconvex Quadratic Program (QP) [F99, Section 2.2]
+# Consider the nonconvex Quadratic Program (QP) from [Floudas1999; Section 2.2](@cite)
 # that minimizes the *concave* function $c^\top x - x^\top Qx / 2$
 # over the polyhedron obtained by intersecting the hypercube $[0, 1]^5$
 # with the halfspace $10x_1 + 12x_2 + 11x_3 + 7x_4 + 4x_5 \le 40$.