Attributes initialized as None not linked in class overview

[jorisvandenbossche]

We experience this issue in the pandas docs (pandas-dev/pandas#6100).

See for example the docstring page for the Index class: http://pandas.pydata.org/pandas-docs/dev/generated/pandas.Index.html. In the list of attributes, at the end, there are some attributes that are not linked to their respective pages.
Eg Index.name, while this page does exist (http://pandas.pydata.org/pandas-docs/dev/generated/pandas.Index.name.html).

This happens for all the attributes that are initialized as None:

In [107]: pd.Index.name is None
Out[107]: True

[jnothman]

Is this fixed? it seems the link is there on the live docs.

But I don't understand why you want to link to an attribute's docs if that attribute is None, and hence their docs are uninformative. Then again, I don't know why you want to autogenerate such docs.

This could be fixed, I think, by using a sentinel other than None in the code, but I'm not entirely convinced that's useful to the user of the docs...

[jnothman]

@jorisvandenbossche, I'm closing this. Reopen if it's still an issue.

[jorisvandenbossche]

Sorry for the late reply. I am not sure this is fixed, but should take the time to look more in detail again.

The reason you don't see it anymore in the current docs is because I added a hack to our vendored numpydoc version to silence the warnings .. (pandas-dev/pandas@70c9d31)

But I don't understand why you want to link to an attribute's docs if that attribute is None, and hence their docs are uninformative. Then again, I don't know why you want to autogenerate such docs.

You are fully correct that the current doc page on eg Index.name (http://pandas-docs.github.io/pandas-docs-travis/generated/pandas.Index.name.html#pandas.Index.name) is completely uninformative. But the main reason I opened this issue is because the previous situation was also annoying: it raised warnings in the doc build and name was still listed in the Index page, but rather in an ugly way. See eg http://pandas.pydata.org/pandas-docs/version/0.15.0/generated/pandas.Index.html

It might also be that this 'uninformativeness' of the doc page could be solved (as the Index.name page could have some useful information listed there, I am just not sure if it is that easy to give a docstring to such an attribute). Because Index.name is not always None, as can some explanation, it is just that in the class definition, it is initialized as None already on the class itself

[jnothman]

but if you describe it in the class docstring you will at least get that description in the class. I don't see how then also linking to a blank page helps!