DOI autolinking (#3644)

* 📝 DOI linking role and directive

* 📝 Convert existing dois

* 🐛 Remove old directive addition

* 📝 Fix docs

CONTRIBUTING.md

@@ -227,7 +227,7 @@ def IPB98y2(
 
   Notes
   -----
-  [2] ITER Physics Expert Group, Nucl. Fus. 39, 12, <https://iopscience.iop.org/article/10.1088/0029-5515/39/12/302/pdf>
+  [2] :doi:`ITER Physics Expert Group, Nucl. Fus. 39, 12 <10.1088/0029-5515/39/12/302>`
 
   \t:math:`\\tau_{E}=0.0562I_p^{0.93}B_t^{0.15}P_{sep}^{-0.69}n^{0.41}M^{0.19}R_0^{1.97}A^{-0.58}\\kappa^{0.78}`
   """

bluemira/equilibria/num_control.py

@@ -79,7 +79,7 @@ def Bz(
 class VirtualController(CoilGroup):
     """
     Represents a pair of virtual coils for the numerical vertical control of
-    the plasma, as described in Jeon, 2015: https://link.springer.com/10.3938/jkps.67.843
+    the plasma, as described in :doi:`Jeon, 2015 <10.3938/jkps.67.843>`
 
     It does work to some extent (perhaps I've implemented it incorrectly). It
     seems to fall over for large numerical instabilities.

bluemira/equilibria/physics.py

@@ -246,7 +246,7 @@ def calc_li3(eq: Equilibrium) -> float:
     Calculates the normalised internal plasma inductance (ITER approximate
     calculation)
 
-    see https://iopscience.iop.org/article/10.1088/0029-5515/48/12/125002/meta
+    see :doi:`10.1088/0029-5515/48/12/125002`
 
     \t:math:`li(3)=\\dfrac{2V\\langle B_p^2\\rangle}{(\\mu_0I_p)^2R_0}`
 

bluemira/equilibria/profiles.py

@@ -91,8 +91,9 @@ def singlepowerfunc(x: float, *args) -> float:
 @nb.jit(nopython=True, cache=True)
 def doublepowerfunc(x: float, *args) -> float:
     """
-    Double power shape function defined e.g. in Lao 1985
-        https://iopscience.iop.org/article/10.1088/0029-5515/25/11/007/pdf \n
+    Double power shape function defined e.g. in
+    :doi:`Lao 1985 <10.1088/0029-5515/25/11/007>`
+
     \t:math:`g(x)=(1-x^{m})^{n}`
     """
     # sign tweak needed to avoid runtimewarnings in np
@@ -191,8 +192,8 @@ def speedy_pressure_mask(
 # @nb.jit(cache=True)
 def laopoly(x: float, *args) -> float:
     """
-    Polynomial shape function defined in Lao 1985
-        https://iopscience.iop.org/article/10.1088/0029-5515/25/11/007/pdf \n
+    Polynomial shape function defined in
+    :doi:`Lao 1985 <10.1088/0029-5515/25/11/007>`
     \t:math:`g(x)=\\sum_{n=0}^{n_F} \\alpha_{n}x^{n}-`
     \t:math:`x^{n_F+1}\\sum_{n=0}^{n_F} \\alpha_{n}`
     """
@@ -206,8 +207,8 @@ def laopoly(x: float, *args) -> float:
 @nb.jit(nopython=True, cache=True)
 def luxonexp(x: float, *args) -> float:
     """
-    Exponential shape function defined in Luxon 1984
-        https://iopscience.iop.org/article/10.1088/0029-5515/22/6/009/meta
+    Exponential shape function defined in
+    :doi:`Luxon 1984 <10.1088/0029-5515/22/6/009>`
     \t:math:`g(x)=\\text{exp}\\big(-\\alpha^2x^2\\big)`
     """
     alpha = args[0]
@@ -506,7 +507,7 @@ def plot(self, ax=None):
 class BetaIpProfile(Profile):
     """
     Constrain poloidal Beta and plasma current following logic as laid out in
-    Jeon, 2015: https://link.springer.com/article/10.3938/jkps.67.843 and
+    :doi:`Jeon, 2015 <10.3938/jkps.67.843>` and
     following some implementation in B. Dudson, FreeGS:
     https://github.com/bendudson/freegs
 

bluemira/equilibria/shapes.py

@@ -95,8 +95,10 @@ def flux_surface_hirshman(
 
     Notes
     -----
-    Hirshman and Neilson, 1986
-    https://pubs.aip.org/aip/pfl/article/29/3/790/944223/External-inductance-of-an-axisymmetric-plasma
+    .. doi:: 10.1063/1.865934
+        :title: Hirshman and Neilson,
+                "External inductance of an axisymmetric plasma", 1986
+
     """
     t = _generate_theta(n)
     eps = a / r_0
@@ -576,10 +578,9 @@ def flux_surface_kuiroukidis(
     """
     Make an up-down asymmetric flux surface with a lower X-point.
 
-    Ap. Kuiroukidis and G. N. Throumoulopoulos, Plasma Phys. Control. Fusion 57  (2015)
-    078001
-
-    DOI: 10.1088/0741-3335/57/7/078001
+    .. doi:: 10.1088/0741-3335/57/7/078001
+        :title: Ap. Kuiroukidis and G. N. Throumoulopoulos,
+                Plasma Phys. Control. Fusion 57 (2015)
 
     Parameters
     ----------

bluemira/fuel_cycle/lifecycle.py

@@ -517,19 +517,19 @@ class LifeCycleParams:
     blk_1_dpa: float = 20
     """
     Starter blanket life limit (EUROfer) [dpa].
-    https://iopscience.iop.org/article/10.1088/1741-4326/57/9/092002/pdf.
+    .. doi:: 10.1088/1741-4326/57/9/092002
     """
 
     blk_2_dpa: float = 50
     """
     Second blanket life limit (EUROfer) [dpa].
-    https://iopscience.iop.org/article/10.1088/1741-4326/57/9/092002/pdf.
+    .. doi:: 10.1088/1741-4326/57/9/092002
     """
 
     div_dpa: float = 5
     """
     Divertor life limit (CuCrZr) [dpa].
-    https://iopscience.iop.org/article/10.1088/1741-4326/57/9/092002/pdf.
+    .. doi:: 10.1088/1741-4326/57/9/092002
     """
 
     vv_dpa: float = 3.25
@@ -538,7 +538,7 @@ class LifeCycleParams:
     tf_fluence: float = 3.2e21
     """
     Insulation fluence limit for ITER equivalent to 10 MGy [1/m^2].
-    https://ieeexplore.ieee.org/document/6374236/.
+    .. doi:: 10.1109/TASC.2012.2231723
     """
 
     tf_ins_nflux: float = 1.4e13
@@ -553,7 +553,7 @@ class LifeCycleParams:
     div_dmg: float = 3
     """
     Divertor neutron damage rate [dpa/fpy].
-    https://iopscience.iop.org/article/10.1088/1741-4326/57/9/092002/pdf.
+    .. doi:: 10.1088/1741-4326/57/9/092002/pdf
     """
 
     vv_dmg: float = 0.3

bluemira/magnetostatics/circular_arc.py

@@ -7,7 +7,7 @@
 Analytical expressions for the field due to a circular current arc of
 rectangular cross-section, following equations as described in:
 
-https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=1064259
+.. doi:: 10.1109/TMAG.1985.1064259
 """
 
 import matplotlib.pyplot as plt

bluemira/magnetostatics/finite_element_2d.py

@@ -59,7 +59,7 @@ class FemMagnetostatic2d:
     .. [Zohm] H. Zohm, Magnetohydrodynamic Stability of Tokamaks, Wiley-VCH, Germany,
        2015
     .. [Villone] VILLONE, F. et al. Plasma Phys. Control. Fusion 55 (2013) 095008,
-       https://doi.org/10.1088/0741-3335/55/9/095008
+       :doi:`10.1088/0741-3335/55/9/095008`
 
     Parameters
     ----------

bluemira/magnetostatics/polyhedral_prism.py

@@ -6,11 +6,13 @@
 """
 Polyhedral prism current source using the volume integral method
 
-The easiest description and structure to follow was M. Fabbri,
-"Magnetic Flux Density and Vector Potential of Uniform Polyhedral Sources",
-IEEE TRANSACTIONS ON MAGNETICS, VOL. 44, NO. 1, JANUARY 2008
 
-https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=4407584
+The easiest description and structure to follow was:
+
+.. doi:: 10.1109/TMAG.2007.908698
+    :title: M. Fabbri,
+            "Magnetic Flux Density and Vector Potential of Uniform Polyhedral Sources",
+            IEEE TRANSACTIONS ON MAGNETICS, VOL. 44, NO. 1, JANUARY 2008
 
 Additional information and detail also present in Passaroto's Master's thesis:
 https://thesis.unipd.it/retrieve/d0269be2-2e5d-4068-af58-4374193d38a1/Passarotto_Mauro_tesi.pdf
@@ -65,7 +67,7 @@ class Fabbri(PolyhedralKernel):
     """
     Fabbri polyhedral prism formulation
 
-    https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=4407584
+    .. doi:: 10.1109/TMAG.2007.908698
     """
 
     @staticmethod

bluemira/magnetostatics/semianalytic_2d.py

@@ -221,7 +221,7 @@ def semianalytic_Bx(
 
     References
     ----------
-    https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=6019053
+    .. doi:: 10.1109/TMAG.2011.2167981
     """
     r1, r2, z1, z2, j_tor = _get_working_coords(xc, zc, x, z, d_xc, d_zc)
 
@@ -273,7 +273,7 @@ def semianalytic_Bz(
 
     References
     ----------
-    https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=6019053
+    .. doi:: 10.1109/TMAG.2011.2167981
     """
     r1, r2, z1, z2, j_tor = _get_working_coords(xc, zc, x, z, d_xc, d_zc)
 

bluemira/magnetostatics/trapezoidal_prism.py

@@ -8,9 +8,11 @@
 Analytical expressions for the field inside an arbitrarily shaped winding pack
 of rectangular cross-section, following equations as described in:
 
-https://onlinelibrary.wiley.com/doi/epdf/10.1002/jnm.594
+.. doi:: 10.1002/jnm.594
+
 including corrections from:
-https://onlinelibrary.wiley.com/doi/abs/10.1002/jnm.675
+
+.. doi:: 10.1002/jnm.675
 """
 
 import numba as nb
@@ -54,7 +56,7 @@ def primitive_sxn_bound(
     Notes
     -----
     Uses corrected formulae available at:
-    https://onlinelibrary.wiley.com/doi/abs/10.1002/jnm.675
+    .. doi:: 10.1002/jnm.675
 
     Singularities all resolve to: lim(ln(1)) --> 0
     """

bluemira/materials/material.py

@@ -943,7 +943,7 @@ class BePebbleBed(UnitCellCompound):
     @staticmethod
     def CTE(temperature: float, eps_vol: float = 0) -> float:  # noqa: N802
         """
-        https://www.sciencedirect.com/science/article/pii/S0920379602001655
+        .. doi:: 10.1016/S0920-3796(02)00165-5
         """
         # NOTE: Effect of inelastic volumetric strains [%] not negligible
         # esp_vol calculated roughly as f(T), as per 2M2BH9

bluemira/plasma_physics/reactions.py

@@ -221,8 +221,8 @@ class BoschHale_DT_4Hen:
 
     D + T --> 4He + n
 
-    H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
-    DOI 10.1088/0029-5515/32/4/I07
+    .. doi:: 10.1088/0029-5515/32/4/I07
+        :title: H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
     """
 
     t_min: float = 0.2  # [keV]
@@ -249,8 +249,8 @@ class BoschHale_DD_3Hen:
 
     D + D --> 3He + n
 
-    H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
-    DOI 10.1088/0029-5515/32/4/I07
+    .. doi:: 10.1088/0029-5515/32/4/I07
+        :title: H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
     """
 
     t_min: float = 0.2  # [keV]
@@ -277,8 +277,8 @@ class BoschHale_DD_Tp:
 
     D + D --> T + p
 
-    H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
-    DOI 10.1088/0029-5515/32/4/I07
+    .. doi:: 10.1088/0029-5515/32/4/I07
+        :title: H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
     """
 
     t_min: float = 0.2  # [keV]
@@ -305,8 +305,8 @@ class BoschHale_DHe3_4Hep:
 
     D + 3He --> 4He + p
 
-    H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
-    DOI 10.1088/0029-5515/32/4/I07
+    .. doi:: 10.1088/0029-5515/32/4/I07
+        :title: H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
     """
 
     t_min: float = 0.5  # [keV]
@@ -345,8 +345,8 @@ def _reactivity_bosch_hale(
 
     Notes
     -----
-    H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
-    DOI 10.1088/0029-5515/32/4/I07
+    .. doi:: 10.1088/0029-5515/32/4/I07
+        :title: H.-S. Bosch and G.M. Hale 1992 Nucl. Fusion 32 611
     """
     if reaction == Reactions.D_D:
         return 0.5 * (

bluemira/plasma_physics/rules_of_thumb.py

@@ -79,8 +79,9 @@ def estimate_Le(A: float, kappa: float) -> float:  # noqa: N802
 
     Notes
     -----
-    Hirshman and Neilson, 1986
-    https://pubs.aip.org/aip/pfl/article/29/3/790/944223/External-inductance-of-an-axisymmetric-plasma
+    .. doi:: 10.1063/1.865934
+        :title: Hirshman and Neilson, 1986
+
     Assuming a LCFS parameterisation as per:
     :py:func:`~bluemira.equilibria.shapes.flux_surface_hirshman`
     """
@@ -114,9 +115,10 @@ def estimate_M(A: float, kappa: float) -> float:  # noqa: N802
 
     Notes
     -----
-    Hirshman and Neilson, 1986
-    https://pubs.aip.org/aip/pfl/article/29/3/790/944223/External-inductance-of-an-axisymmetric-plasma
-    Assuming a LCFS parameterisation as per:
+    .. doi:: 10.1063/1.865934
+        :title: Hirshman and Neilson, 1986
+
+    Assuming a LCFS parameterisation as per
     :py:func:`~bluemira.equilibria.shapes.flux_surface_hirshman`
     """
     eps = 1 / A

bluemira/plasma_physics/scaling_laws.py

@@ -145,8 +145,7 @@ def lambda_q(
 
     Notes
     -----
-    [4] Eich et al., 2011
-        <https://journals.aps.org/prl/pdf/10.1103/PhysRevLett.107.215001>
+    [4] :doi:`Eich et al., 2011 <10.1103/PhysRevLett.107.215001>`
 
     \t:math:`\\lambda_q=(0.73\\pm0.38)B_t^{-0.78\\pm0.25}q_{95}^{1.2\\pm0.27}P_{SOL}^{0.1\\pm0.11}R_{0}^{0.02\\pm0.2}`
     """
@@ -189,9 +188,7 @@ def P_LH(  # noqa: N802
 
     Notes
     -----
-    [3] Martin et al., 2008,
-    <https://infoscience.epfl.ch/record/135655/files/1742-6596_123_1_012033.pdf>
-    equation (3)
+    [3] Martin et al., 2008, :doi:`10.1088/1742-6596/123/1/012033` equation (3)
 
     \t:math:`P_{LH}=2.15e^{\\pm 0.107}n_{e20}^{0.782 \\pm 0.037}`
     \t:math:`B_{T}^{0.772 \\pm 0.031}a^{0.975 \\pm 0.08}R_{0}^{0.999 \\pm 0.101}`
@@ -252,8 +249,7 @@ def IPB98y2(  # noqa: N802
 
     Notes
     -----
-    [2] ITER Physics Expert Group, Nucl. Fus. 39, 12, <https://iopscience.iop.org/article/10.1088/0029-5515/39/12/302/pdf>
-    equation (20)
+    [2] :doi:`ITER Physics Expert Group, Nucl. Fus. 39, 12 <10.1088/0029-5515/39/12/302>`
 
     \t:math:`\\tau_{E}=0.0562I_p^{0.93}B_t^{0.15}P_{sep}^{-0.69}n^{0.41}M^{0.19}R_0^{1.97}A^{-0.58}\\kappa^{0.78}`
     """

bluemira/radiation_transport/neutronics/constants.py

@@ -71,10 +71,10 @@ class DPACoefficients:
 
     Notes
     -----
-    Shengli Chena, David Bernard
-    On the calculation of atomic displacements using damage energy
-    Results in Physics 16 (2020) 102835
-    https://doi.org/10.1016/j.rinp.2019.102835
+    .. doi:: 10.1016/j.rinp.2019.102835
+        :title: Shengli Chena, David Bernard,
+                "On the calculation of atomic displacements using damage energy"
+                Results in Physics 16 (2020)
     """
 
     def __init__(