Inclusing static types in docs breaks references

[paddyroddy]

What is the Topic of Your Question

Documentation

Add Your Question Below

Prior to #347 we were using numpydoc, but I can't get it to work type annotations numpy/numpydoc#196. I have switched to napolean which is what Heracles uses. The problem is this now breaks the references sphinx-doc/sphinx#9689 as we have "duplicate" ones, and they are considered global. I propose moving to bibtex for references like they did here lenskit/lkpy#273. Are we happy with this?

[ntessore]

Not a fan of the bibtex solution, for how far it separates the reference and the doctstring.

As an immediate fix, can we turn the list of references into a plain numbered list, and simply remove the _ from the references [1]_ etc.? So we get text like

def nnls(
    a: npt.ArrayLike,
    b: npt.ArrayLike,
    *,
    tol: float = 0.0,
    maxiter: int | None = None,
) -> npt.ArrayLike:
    """
    Compute a non-negative least squares solution.

    Implementation of the algorithm due to [1] as described in [2].

    References
    ----------
    * [1] Lawson, C. L. and Hanson, R. J. (1995), Solving Least Squares
        Problems. doi: 10.1137/1.9781611971217
    * [2] Bro, R. and De Jong, S. (1997), A fast
        non-negativity-constrained least squares algorithm. J.
        Chemometrics, 11, 393-401.

    """

[paddyroddy]

Ah yeah that would work, the downside being is you don't get the nice hyperlink you would get with sphinx.ext.napolean

[ntessore]

I think that's acceptable, given everything has a downside here. Those links usually only take you a couple of inches down the screen.

At the same time, we should try and get the sphinx issue reopened, as that is a very clear error in terms of how numpydoc-style docstrings are meant to operate. See here: https://numpydoc.readthedocs.io/en/latest/format.html#references.

[paddyroddy]

Makes sense, I will try, but anticipate backlash

[paddyroddy]

"Fixed" in #347, closing in favour of #351.