Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: test new sphinx 2 release #26058

Closed
jorisvandenbossche opened this issue Apr 12, 2019 · 14 comments
Closed

DOC: test new sphinx 2 release #26058

jorisvandenbossche opened this issue Apr 12, 2019 · 14 comments
Labels
CI Continuous Integration Docs

Comments

@jorisvandenbossche
Copy link
Member

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
@jorisvandenbossche jorisvandenbossche added Docs CI Continuous Integration labels Apr 12, 2019
@jorisvandenbossche jorisvandenbossche added this to the Contributions Welcome milestone Apr 12, 2019
@saurav2608
Copy link

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

@jorisvandenbossche
Copy link
Member Author

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
Copy link

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

@saurav2608
Copy link

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
Copy link
Member Author

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
Copy link
Member Author

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
Copy link

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

@jorisvandenbossche
Copy link
Member Author

jorisvandenbossche commented Apr 18, 2019

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
Copy link
Member Author

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
Copy link
Member

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

image

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

also

image

have extra backslashes for the *args, **kwargs

@jorisvandenbossche
Copy link
Member Author

Yep, that seem to be yet some more theme issues with the latest sphinx ...

Some others are the one I mentioned above, and also the too much white space in the in-page table of contents, eg at http://pandas-docs.github.io/pandas-docs-travis/development/contributing.html

@jorisvandenbossche
Copy link
Member Author

Another thing I noticed is that the API pages now include self in the signature (not sure it is related to sphinx 2.x), but at least it is something present in the dev docs and not stable docs.

Eg http://pandas-docs.github.io/pandas-docs-travis/reference/api/pandas.DataFrame.mean.html vs http://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.mean.html#pandas.DataFrame.mean

@jorisvandenbossche
Copy link
Member Author

jorisvandenbossche commented Jun 11, 2019

the API pages now include self in the signature

From a quick test, this does not seem to be related to sphinx above or below 2.0, but also couldn't point it something else (eg version of numpydoc)

Update -> this is caused by numpydoc regression: numpy/numpydoc#220

@mroeschke
Copy link
Member

Looks like we're using Sphinx 3 now in our doc builds. Don't think Sphinx 2 issues are relevant anymore, but happy to open a new issue to discuss if there are any Sphinx 3 issues that we're experiencing

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CI Continuous Integration Docs
Projects
None yet
Development

No branches or pull requests

4 participants