New build warnings for SciPy doc build due to f2py changes in 1.22.0 #20696
Description
We are getting doc build warnings (which get turned into failures in CI) when building against numpy 1.22.0. See scipy/scipy#15327 (comment)
The full set of warnings is:
docstring of scipy.linalg.lapack.ssyevr:16: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.ssyevr:22: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.ssyevr:22: WARNING: Inline emphasis start-string without end-string.
docstring of scipy.linalg.lapack.ssyevr:22: WARNING: Inline emphasis start-string without end-string.
docstring of scipy.linalg.lapack.ssyevx:16: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.ssyevx:22: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.zheevr:16: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.zheevx:16: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.zheevx:16: WARNING: Inline emphasis start-string without end-string.
docstring of scipy.linalg.lapack.dsyevr:16: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.dsyevr:22: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.dsyevr:22: WARNING: Inline emphasis start-string without end-string.
docstring of scipy.linalg.lapack.dsyevr:22: WARNING: Inline emphasis start-string without end-string.
docstring of scipy.linalg.lapack.dsyevx:16: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.dsyevx:22: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.cheevr:16: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.cheevx:16: WARNING: Inline literal start-string without end-string.
docstring of scipy.linalg.lapack.cheevx:16: WARNING: Inline emphasis start-string without end-string
This means that there are unescaped special ReST characters (*, _) in the autogenerated docstrings. These docstrings generated by f2py look like (from build/scipy/linalg/_flapackmodule.c):
/*********************************** cheevr ***********************************/
static char doc_f2py_rout__flapack_cheevr[] = "\
w,z,m,isuppz,info = cheevr(a,[compute_v,range,lower,vl,vu,il,iu,abstol,lwork,lrwork,liwork,overwrite_a])\n\nWrapper for ``cheevr``.\
\n\nParameters\n----------\n"
"a : input rank-2 array('F') with bounds (n,n)\n"
"\nOther Parameters\n----------------\n"
"compute_v : input int, optional\n Default: 1\n"
"range : input string(len=1), optional\n Default: 'A'\n"
"lower : input int, optional\n Default: 0\n"
"overwrite_a : input int, optional\n Default: 0\n"
"vl : input float, optional\n Default: 0.0\n"
"vu : input float, optional\n Default: 1.0\n"
"il : input int, optional\n Default: 1\n"
"iu : input int, optional\n Default: n\n"
"abstol : input float, optional\n Default: 0.0\n"
"lwork : input int, optional\n Default: max(2*n,1)\n"
"lrwork : input int, optional\n Default: max(24*n,1)\n"
"liwork : input int, optional\n Default: max(1,10*n)\n"
"\nReturns\n-------\n"
"w : rank-1 array('f') with bounds (n)\n"
"z : rank-2 array('F') with bounds ((compute_v?MAX(0,n):0),(compute_v?(*range=='I'?iu-il+1:MAX(1,n)):0))\n"
"m : int\n"
"isuppz : rank-1 array('i') with bounds (2*max(1,n))\n"
"info : int";
I've looked into it a bit, but it's hard to figure out exactly which ones are the problematic characters, or what were the relevant changes in f2py. For now we're pinning the SciPy doc build to numpy 1.21.5; it'd be good if someone could investigate.