DOC: autosummary table summary lines (sphinx 1.2.1)

[jorisvandenbossche]

Related to #5899.

With the release of Sphinx 1.2.1, there is also a change in the behaviour of sphinx.ext.autosummary in how to define the text shown in the autosummary table (the tables you see here: http://pandas.pydata.org/pandas-docs/dev/api.html).

See:

• sphinx issue: https://bitbucket.org/birkenfeld/sphinx/issue/943/autosummary-doesnt-always-get-first
• http://stackoverflow.com/questions/10718846/use-first-paragraph-instead-of-first-line-in-sphinx-autosummary

Summary: the regex to define the part (idea: the first sentence) of the docstring that is used as the summary line in the tables has changed to allow the first sentence to be longer than the first line.

Consequence for pandas: The new regex searches for the end of the first sentence on all lines. In case of pandas docstrings, which are not that cleaned up to always have a period . at the end of the first line, this will sometimes give a first sentence including part of the parameter explanations.
Result: messy table in api.html

To do: go over all docstrings of public functions to adapt first sentence.
They should look like this:

Short summary line.

Optionally longer explanation.
bla bla

Parameters
----------
...

where especially the period . after the first short line is important.

[jreback]

0.14 for this?

[jorisvandenbossche]

As long as we build the docs with sphinx 1.1.3, it doesn't matter. So not a blocker.

[jorisvandenbossche]

OK, this was fixed in Sphinx itself, in version 1.2.2 (http://sphinx-doc.org/changes.html#release-1-2-2-released-mar-2-2014), so closing!

[jreback]

should update the dev install docs then?

[jorisvandenbossche]

I was just looking at those :-)
It says at least 1.2.1, I will make that 1.2.2 then

[jorisvandenbossche]

Here: http://pandas.pydata.org/pandas-docs/stable/contributing.html#requirements
Do you know of other places where this is mentioned?

[jreback]

maybe on pandas-website somewhere.

Actually easiest way to do this is to create a public conda recipe for doing this and post here: https://github.com/conda/conda-recipes (then point the docs to this recipe) (then you can simply specify a minimum version for libraries, eg. sphinx)

then ``conda build recipe_dir; conda install <package> --use-local will install deps

@cpcloud