Method summary table in HTML docs is empty

[embray]

The method summary table in the HTML docs is empty:

Example: http://astropy.readthedocs.org/en/latest/api/astropy.table.Table.html

I think this affects all Astropy classes and affiliated packages (at least it does in Gammapy).

@eteq @embray Any idea how to fix that?

[embray]

Sorry, at first I thought you meant the attribute summary (since some of the attributes appear to be missing docstrings). But now I see what you mean.

[embray]

If I can figure this out quickly it would be good to have fixed for v1.1.

[embray]

So on the referenced Table docs (for example) the page source contains:

   .. rubric:: Attributes Summary

   .. autosummary::

      ~Table.ColumnClass
      ~Table.colnames
      ~Table.dtype
      ~Table.groups
      ~Table.has_mixin_columns
      ~Table.iloc
      ~Table.indices
      ~Table.info
      ~Table.loc
      ~Table.mask
      ~Table.masked







   .. rubric:: Methods Summary

   .. autosummary::

      ~Table.add_column
      ~Table.add_columns
      ~Table.add_index
      ~Table.add_row
      ~Table.argsort
      ~Table.as_array
      ~Table.convert_bytestring_to_unicode
      ~Table.convert_unicode_to_bytestring
      ~Table.copy
      ~Table.field
      ~Table.filled
      ~Table.from_pandas
      ~Table.group_by
      ~Table.index_column
      ~Table.index_mode
      ~Table.insert_row
      ~Table.keep_columns
      ~Table.keys
      ~Table.more
      ~Table.pformat
      ~Table.pprint
      ~Table.read
      ~Table.remove_column
      ~Table.remove_columns
      ~Table.remove_indices
      ~Table.remove_row
      ~Table.remove_rows
      ~Table.rename_column
      ~Table.replace_column
      ~Table.reverse
      ~Table.show_in_browser
      ~Table.show_in_notebook
      ~Table.sort
      ~Table.to_pandas
      ~Table.write

So it should be showing the autosummary for those methods. It's strange also that it's working for the attributes summary but now for the methods summary.

The docs are being built with Sphinx 1.3.1 on RTD, so it should just be using the original autosummary from Sphinx (as opposed to the old Astropy wrapper around it). So this could be a bug in Sphinx? Not sure though...

[eteq]

@embray @cdeil - I took a look at this, and I don't think this is a sphinx problem: at least in Table, I see this:

In [13]: table.Table.ColumnClass?
Type:        property
String form: <property object at 0x10940f8e8>
Docstring:   <no docstring>

In [14]: table.Table.colnames?
Type:        property
String form: <property object at 0x10940f9f0>
Docstring:   <no docstring>

In [15]: table.Table.dtype?
Type:        property
String form: <property object at 0x10940f998>
Docstring:   <no docstring>

In [16]: table.Table.has_mixin_columns?
Type:        property
String form: <property object at 0x10940f890>
Docstring:
True if table has any mixin columns (defined as columns that are not Column
subclasses)

That is, sphinx is just reading the docstring for those attributes and finding no docstring: that's because they are all properties without any docstring defined. So the "fix" is instead to go and document the property in astropy core.

Or are there other examples where there's actually a docstring but the table isn't printing them? If not, I think this issue can be closed without change (but certainly a new column issue could be made to document these properties)

[embray]

@eteq I think you misread the problem. The problem is with the "Methods Summary", not the "Attributes Summary".

[embray]

I confirmed that the Methods Summary is generated just fine when building with Sphinx 1.2, but breaks on Sphinx 1.3, so definitely something changed in Sphinx to make this stop working.

[embray]

Ah, I see--this is related to the comment I made way back in March here: sphinx-doc/sphinx#1061 (comment)

There have been many other issues related to this. I'll dig around to see if there's an existing solution...

[embray]

Okay, this was fixed in sphinx-doc/sphinx#1892. I'll see if I can come up with a workaround... (should be easy enough with a small monkey-patch to Autosummary I think...)

[embray]

D'oh--this is actually the same problem that 27f2924 was meant to work around. I'm sure the workaround used to work, so I'm not sure why it's stopped working...?

[embray]

I see now. I fixed this for the Automodsumm extension that we wrote (which is based on Autosummary). However, this is a case of the same bug affecting the plain Autosummary extension.

Ironically we used to ship our own version of Autosummary (which added some features missing from the original version), but I deprecated it since we didn't need it for Sphinx 1.2. However Sphinx 1.3 contains a new bug so I guess we need to override the base Autosummary again.... :(

[embray]

The attached patch fixes it. Since this is just a workaround to an upstream bug I haven't attached a test, but I have confirmed manually that this fixes it.

[eteq]

@embray - oops, yeah, you're right, I was confused about the actual problem here.

Curiously enough, I independently fixed the exact same problem just yesterday in a much hackier way (astropy/halotools#245). This is definitely a better solution! Looks good to me assuming the tests pass.

[embray]

Oops--too bad about the wasted duplicate effort.

[bsipocz]

This was merged to master before 1.1.0 no matter what the release scripts say (was part of a nested master merge, thus not picked up).