50 clean citations (#64)

closes #50 

should be evaluated in combination with:
mesh-adaptation/movement#132
mesh-adaptation/animate#160
mesh-adaptation/goalie#232

Locally the main warnings remaining after all the PRs should be about
'duplicate_citations', though all citations should still render.

---------

Co-authored-by: Davor Dundovic <33790330+ddundo@users.noreply.github.com>
Co-authored-by: acse-ej321 <acse-ej321@github.com>

docs/Makefile

@@ -48,20 +48,20 @@ copy_demos:
 	install -d source/demos
 	cp ${ANIMATE}/demos/*.py source/demos
 	cp ${ANIMATE}/demos/*.jpg source/demos
-	cp ${ANIMATE}/demos/demo_references.bib source/demos
+	cp ${ANIMATE}/demos/*.svg source/demos
+
 	cp ${GOALIE}/demos/*.py source/demos
 	cp ${GOALIE}/demos/*.jpg source/demos
-	cat ${GOALIE}/demos/demo_references.bib >> source/demos/demo_references.bib
+
 	cp ${MOVEMENT}/demos/*.py source/demos
 	cp ${MOVEMENT}/demos/*.jpg source/demos
-	cat ${MOVEMENT}/demos/demo_references.bib >> source/demos/demo_references.bib
+
 	for FILE in source/demos/*.py; do \
 		pylit -c $$FILE; mv $$FILE.txt $$FILE.rst; \
 	done
 	install -d $(BUILDDIR)/html/demos
 	cp source/demos/*.py $(BUILDDIR)/html/demos
 	cp source/demos/*.jpg $(BUILDDIR)/html/demos
-	cp source/demos/*.bib $(BUILDDIR)/html/demos
 	install -d $(BUILDDIR)/html/animate
 	install -d $(BUILDDIR)/html/goalie
 	install -d $(BUILDDIR)/html/movement

docs/source/animate/1-metric-based.rst

@@ -161,7 +161,7 @@ represented by a unit circle.
    :align: center
 
    Representation of a 2D Riemannian metric as an ellipse.
-   Image taken from :cite:`Wallwork:21` with author's permission.
+   Image taken from :cite:`Wallwork:2021` with author's permission.
 
 Given a metric field, the eigendecomposition may be
 computed in Goalie using the function
@@ -218,7 +218,7 @@ using the function :func:`~.density_and_quotients`.
 Continuous mesh analogy
 -----------------------
 
-The work of :cite:`LA:11` established duality between
+The work of :cite:`Loseille:2011` established duality between
 the (inherently discrete) mesh and a (continuous)
 Riemannian metric field. Having a continuous
 representation for the mesh means that we are able to
@@ -371,15 +371,15 @@ which fits within the ellipses associtated with the
 two input metrics. As such, metric intersection yields
 a new metric whose complexity is greater than (or equal
 to) its parents'. This is not true for the metric
-average in general. See :cite:`PUDG:01` for details.
+average in general. See :cite:`Pain:2001` for details.
 
 .. figure:: images/intersection.jpg
    :figwidth: 80%
    :align: center
 
    Intersection of two 2D Riemannian metrics, interpreted
    in terms of their elliptical representations.
-   Image taken from :cite:`Wallwork:21` with author's permission.
+   Image taken from :cite:`Wallwork:2021` with author's permission.
 
 Metric combination may be achieved in Goalie using the
 function :func:`~.combine_metrics`, which defaults to the
@@ -389,4 +389,5 @@ metric average.
 References
 ----------
 
-.. bibliography:: 1-references.bib
+.. bibliography::
+   :filter: docname in docnames

docs/source/conf.py

@@ -68,9 +68,9 @@
 # built documents.
 #
 # The short X.Y version.
+import goalie
 import animate
 import movement
-import goalie
 import UM2N
 
 version = "0.1"
@@ -124,6 +124,13 @@
     "css_files": ["_static/custom.css"],
 }
 
+# Modify content of sidebar to not include next/previous sections
+# as they are not currently used
+# reference:
+# https://stackoverflow.com/questions/18969093/how-to-include-the-toctree-in-the-sidebar-of-each-page
+html_sidebars = {
+    '**': ['localtoc.html', 'sourcelink.html', 'searchbox.html'] 
+}
 
 # -- Options for HTMLHelp output ------------------------------------------
 
@@ -204,10 +211,7 @@
 
 #  -- Options for sphinxcontrib.bibtex ------------------------------------
 bibtex_bibfiles = [
-    "references.bib",
-    "demos/demo_references.bib",
-    "animate/1-references.bib",
-    "goalie/1-references.bib",
-    "goalie/2-references.bib",
-    "goalie/3-references.bib",
+    "references.bib"
 ]
+bibtex_default_style = 'alpha'
+bibtex_reference_style = 'author_year'

docs/source/goalie/1-motivation.rst

@@ -56,7 +56,7 @@ governed by the PDE
 
 where :math:`\mathbf u` is the advective velocity, :math:`D` is the
 diffusion coefficient and :math:`S` represents the source term.
-Consider the "point discharge with diffusion" test case from :cite:`RCJ:14`.
+Consider the "point discharge with diffusion" test case from :cite:`Riadh:2014`.
 That is, we have a rectangular domain, within which the fluid velocity
 goes uniformly from left to right, i.e. :math:`\mathbf u=(1,0)`.
 In such a case, we have an inflow across the left-hand boundary and
@@ -70,7 +70,7 @@ channel sides, we are able to formulate and solve the problem numerically.
    :align: center
 
    Finite element solution of the tracer transport problem.
-   Image taken from :cite:`WBHP:22` with authors' permission.
+   Image taken from :cite:`Wallwork:2022` with authors' permission.
 
 In the above plot, the source term is centred at :math:`(2,5)`.
 Tracer concentration is released, advected to the right and diffused
@@ -97,7 +97,7 @@ below.
    :align: center
 
    Finite element solution of the adjoint tracer transport problem.
-   Image taken from :cite:`WBHP:22` with authors' permission.
+   Image taken from :cite:`Wallwork:2022` with authors' permission.
 
 Here the receiver region becomes a `source` for the adjoint problem.
 Further, where the flow goes from left to right in the forward
@@ -138,7 +138,7 @@ meshes.
    :align: center
 
    Goal-oriented adapted meshes generated using various metric strategies.
-   Images taken from :cite:`WBHP:22` with authors' permission.
+   Images taken from :cite:`Wallwork:2022` with authors' permission.
 
 The adapted meshes take rather different forms, but there are a number of
 features that they have in common. For example, each of them deploy most
@@ -153,4 +153,5 @@ ideas and fundamental mathematical results.
 References
 ----------
 
-.. bibliography:: 1-references.bib
+.. bibliography::
+   :filter: docname in docnames

docs/source/goalie/2-goal-oriented-error-estimation.rst

@@ -63,7 +63,7 @@ This is the equation that we solve when we call
 Recall that we seek to accurately evaluate :math:`J` using a finite element
 method. This is the same as saying that we seek to minimise the "QoI error"
 :math:`J(u)-J(u_h)`. The fundamental result in goal-oriented error estimation
-is the first order *dual weighted residual* result :cite:`BR:01`,
+is the first order *dual weighted residual* result :cite:`Becker:2001`,
 
 .. math::
     :label: dwr1
@@ -101,4 +101,5 @@ using :meth:`~.GoalOrientedMeshSeq.indicate_errors`. See `the Burgers error esti
 References
 ----------
 
-.. bibliography:: 2-references.bib
+.. bibliography::
+   :filter: docname in docnames

docs/source/goalie/3-goal-oriented-mesh-adaptation.rst

@@ -90,7 +90,7 @@ The metric-based framework has been the main backend used for
 goal-oriented mesh adaptation during the development of Goalie.
 However, this does not mean other approaches would not work.
 Mesh movement (or :math:`r`-adaptation) has been implemented in
-Firedrake on a number of occasions (such as :cite:`MCB:18,CWK+:22`)
+Firedrake on a number of occasions (such as :cite:`McRae:2018,Clare:2022`)
 and could plausibly be driven by goal-oriented error estimates.
 
 Fixed point iteration loops
@@ -154,4 +154,5 @@ similarly deduced if the error estimate value changes by less than
 References
 ----------
 
-.. bibliography:: 3-references.bib
+.. bibliography::
+   :filter: docname in docnames

docs/source/goalie/index.rst

@@ -40,6 +40,7 @@ be searched using the inbuilt :ref:`search engine <search>`.
     Solid body rotation <../demos/solid_body_rotation.py>
     Advection-diffusion-reaction <../demos/gray_scott.py>
     Advection-diffusion-reaction with multiple prognostic variables <../demos/gray_scott_split.py>
+    Mantle convection <../demos/mantle_convection.py>
 
 *Error estimation*
 

docs/source/index.rst

@@ -54,3 +54,13 @@ The source codes for all four packages are hosted on GitHub:
 `Movement <https://github.com/mesh-adaptation/movement/>`__,
 `Goalie <https://github.com/mesh-adaptation/goalie/>`__.
 `UM2N <https://github.com/mesh-adaptation/UM2N/>`__.
+
+.. toctree::
+   :hidden:
+
+   self
+   References <references>
+   Animate <animate/index>
+   Movement <movement/index>
+   Goalie <goalie/index>
+   UM2N <UM2N>