DOC: possible cookbook rendering issue with PR #22761

[dsaxton]

When building the cookbook documentation locally I noticed that the function distcorr under the Computation header is getting cut off at the first empty line (PR #22761 and commit 904af03c36b63d8df911b5cdba1e29e66c6df4b4). I tried adding white space indentation but that doesn't seem to have helped. Anyone have ideas as to what the issue might be?

[datapythonista]

Yes, that seems to be the case in the documentation generated on the server: https://pandas-docs.github.io/pandas-docs-travis/cookbook.html#correlation

I'm not sure why the ipython directive doesn't like blank lines in functions. Seems like a bug/limitation in the directive. @jorisvandenbossche may be you know?

.. ipython:: python

    def distcorr(x, y):
        n = len(x)
        a = np.zeros(shape=(n, n))
        b = np.zeros(shape=(n, n))

        for i in range(n):
            for j in range(i + 1, n):
                a[i, j] = abs(x[i] - x[j])
                b[i, j] = abs(y[i] - y[j])

        a += a.T
        b += b.T

        a_bar = np.vstack([np.nanmean(a, axis=0)] * n)
        b_bar = np.vstack([np.nanmean(b, axis=0)] * n)

        A = a - a_bar - a_bar.T + np.full(shape=(n, n), fill_value=a_bar.mean())
        B = b - b_bar - b_bar.T + np.full(shape=(n, n), fill_value=b_bar.mean())

        cov_ab = np.sqrt(np.nansum(A * B)) / n
        std_a = np.sqrt(np.sqrt(np.nansum(A**2)) / n)
        std_b = np.sqrt(np.sqrt(np.nansum(B**2)) / n)

        return cov_ab / std_a / std_b

    df = pd.DataFrame(np.random.normal(size=(100, 3)))

    df.corr(method=distcorr)

[jorisvandenbossche]

I first thought it was related to what @TomAugspurger reported about a regression in IPython regarding functions in code blocks (#22990), but since he pinned IPython to an older version in the doc build, that shouldn't be the case.

So it seems that all our other function definitions in the docs have no blank lines in their function body (so maybe for a reason ...).

In any case, I think we can consider this a bug in the ipython directive? (or absent feature)

[dsaxton]

@jorisvandenbossche Not too familiar with how this stuff works, but would this be a sphinx issue or perhaps one with the documentation build itself?

[datapythonista]

We are using this sphinx plugin for this part: https://jupyter.readthedocs.io/en/latest/development_guide/sphinx_directive.html

And it's this plugin that is likely to have a bug affecting us. Ideally we should do a bit more research about the bug, see if it's happening in the latest version of the plugin, write a minimal example to reproduce the problem, open an issue in the plugin project, and add the link here.

And at the same time, use the regular code-block :: python I suggested in the PR to solve the problem, if can't be fixed in a better way (like updating the plugin version).

Does this make sense?

[dsaxton]

@datapythonista Yes, that makes sense. Thanks