DOC: test new sphinx 2 release

[jorisvandenbossche]

The docs are currently being built with sphinx 1.8.5 (see eg https://travis-ci.org/pandas-dev/pandas/jobs/518832177 for a recent build on master).

Sphinx has released 2.0.0 (http://www.sphinx-doc.org/en/master/changes.html#release-2-0-0-released-mar-29-2019), and it would be good to test our docs with this new release, and see if we need to make changes / report regressions to sphinx.

For somebody wanting to tackle this:

• test it locally to see if there are big problems with building the docs
• make a PR that ensures sphinx 2 is installed in the doc environment, so we can check the build log on travis (I am actually not fully sure why it is not yet picking up sphinx 2 on travis, since we don't pin the version in the travis-36-doc.yaml file

[saurav2608]

I think the anaconda version is still 1.8.5.
https://anaconda.org/anaconda/sphinx

[jorisvandenbossche]

Yes, but we are also listing conda-forge as a second channel, and there it is already updated, so I would expected the environment solver to get the newest version from there. Anyway, it is installing 1.8.5 on travis, that's the relevant part here ;)

[saurav2608]

Yes. I agree. I manually installed version 2.0.1 on local and creating a doc build now.

[saurav2608]

BTW, Sphinx 2.0.1 is part of conda now. And our doc build are using v 2.0.1 to build docs. I do not think there are any issues with the upgrade.

[jorisvandenbossche]

Ah, thanks for noticing! I see one "RemovedInSphinx30Warning" in the logs, but that is probably coming from nbsphinx. For the rest everything indeed seems fine.

[jorisvandenbossche]

One thing I am noticing is that the API pages lost a bit of their styling. Compare http://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.melt.html#pandas-melt with http://pandas-docs.github.io/pandas-docs-travis/reference/api/pandas.melt.html#pandas-melt

It seems sphinx changes how field lists are converted to html, so our custom css (in doc/source/themes/nature_with_gtoc/static/nature.css_t) is no longer matching that.

[saurav2608]

Also whole bunch of warnings RuntimeWarning: You are using an unsupported version of pandoc (2.2.3.2).

[jorisvandenbossche]

Also whole bunch of warnings RuntimeWarning: You are using an unsupported version of pandoc (2.2.3.2).

Yes, but those are not new. They will go away once a new nbconvert release is out, so we can ignore them for now

[jorisvandenbossche]

So with sphinx 1.8.5, you get something like (for the Parameters section of the pandas.melt docstring):

<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><dl class="first last docutils">
<dt><strong>frame</strong> <span class="classifier-delimiter">:</span> <span class="classifier">DataFrame</span></dt>
<dd></dd>
<dt><strong>id_vars</strong> <span class="classifier-delimiter">:</span> <span class="classifier">tuple, list, or ndarray, optional</span></dt>
<dd><p class="first last">Column(s) to use as identifier variables.</p>
</dd>
<dt><strong>value_vars</strong> <span class="classifier-delimiter">:</span> <span class="classifier">tuple, list, or ndarray, optional</span></dt>
<dd><p class="first last">Column(s) to unpivot. If not specified, uses all columns that
are not set as <cite>id_vars</cite>.</p>
</dd>
...

while with sphinx 2.0, it is now:

<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>frame</strong><span class="classifier">DataFrame</span></dt><dd></dd>
<dt><strong>id_vars</strong><span class="classifier">tuple, list, or ndarray, optional</span></dt><dd><p>Column(s) to use as identifier variables.</p>
</dd>
<dt><strong>value_vars</strong><span class="classifier">tuple, list, or ndarray, optional</span></dt><dd><p>Column(s) to unpivot. If not specified, uses all columns that
are not set as <cite>id_vars</cite>.</p>
</dd>
<dt><strong>var_name</strong><span class="classifier">scalar</span></dt><dd><p>Name to use for the ‘variable’ column. If None it uses
<code class="docutils literal notranslate"><span class="pre">frame.columns.name</span></code> or ‘variable’.</p>
</dd>
...

So before, there was a html table with class="docutils field-list", and this was styled specifically in our custom css, which broke due to this change in the generated html. And the same happens in the scipy sphinx theme:

https://github.com/scipy/scipy-sphinx-theme/blob/f0d96ae2bf3b010ce53adadde1e38997497a513e/_theme/scipy/static/scipy.css_t#L111-L156

So it might be that with readthedocs there is a similar issue.

[simonjayhawkins]

so not sure if this is applicable, but on http://pandas-docs.github.io/pandas-docs-travis/reference/indexing.html

is now center justified and was left justified in 0.24.2. (probably would be better to be full width)

also

have extra backslashes for the *args, **kwargs