Repository navigation
automodapi produces page titles that are too long #243
Description
@eteq
For example, on
http://astropy.readthedocs.org/en/latest/_generated/astropy.config.configuration.InvalidConfigurationItemWarning.html
the page title is "astropy.config.configuration.InvalidConfigurationItemWarning". Such a long single "word" causes overflow in the sidebar links.
A simple fix would be to set the title to, e.g., "InvalidConfigurationItemWarning" but keep everything else the same.
Activity
astrofrog commentedon May 29, 2012
Yes, this is an issue regardless of the sphinx theme we use (in the left menubar of the readthedocs version you can see the title name is truncated). I agree that the main title could just be the object name, since the API then makes it clear where this object/function is located. It's worth the try.
eteq commentedon May 30, 2012
Hmm... I kind of like the fact that the name shows exactly where you are in the module... And I am also concerned that we then still have to make sure that attribute names also stay short enough. What would you think of instead figuring out how to get this "word" to wrap onto the next line? Or do you prefer just the short title independent of the wrapping problem?
I have a vaugue memory of @iguananaut mentioning something about a fix to this - do you have any thoughts? Also, @mdboom and @taldcroft , who have both participated in some of these doc discussions, what do you think?
mdboom commentedon May 30, 2012
Adding the following to
astropy.cssis somewhat of a solution:I say "somewhat" because it breaks the word wherever it wants to. I don't think there's a CSS directive to tell it to only break on periods.
mdboom commentedon May 30, 2012
The more I look at this, the more I'm convinced that the readthedocs style is a nice compromise solution to this problem -- the full text is displayed when hovering over the links in the sidebar.
eteq commentedon May 30, 2012
Yeah, I agree the RTD approach is the best one - @kbarbary mentioned this in #209, so I think it might make sense to do that if it's possible.
kbarbary commentedon May 31, 2012
I updated #209 to use the RTD behavior for this. View it here: http://kbarbary.github.com/astropy-docs/configs.html
This is OK with me, but I still think it is less helpful to be able to see a whole bunch of
astropy.config. ...(..and then the rest is cut off) rather than seeing what the actual name of the function is. So I would still prefer to shorten it. In the table generated by automodapi, only the short names of functions and classes are listed. It would be nice if the stuff in the table of contents in the sidebar corresponded to these.astrofrog commentedon May 31, 2012
I agree with @kbarbary and I see @eteq's point about seeing the origin. What about having the TOC have:
Configuration System (astropy.config) # in line with new docs template
data.get_file_obj()
data.get_data_contents()
data.get_data_filename()
...
which shows the origin in the docs, and then on each page we'd have:
get_data_contents
astropy.config.data.get_data_contents(dataname, cache=True)
instead of
astropy.config.data.get_data_contents
astropy.config.data.get_data_contents(dataname, cache=True)
which is redundant anyway? Then everyone is happy :-)
astrofrog commentedon May 31, 2012
In fact, should the full list of functions/methods actually ever be in the TOC as opposed to the tables? I think that the headers in the TOC should just be descriptive ones, e.g.
http://kbarbary.github.com/astropy-docs/table/index.html
So maybe once the docs are tidied up this won't be an issue anyway? (though I still agree with shortening the title on the individual function pages, since the full path is already listed twice).
eteq commentedon Jun 1, 2012
@astrofrog - your first proposal sounds fine to me. Should I go ahead and implement that in automodapi?
I think it is useful to have the functions/classes in the TOC, though, because that's often a useful way to jump around. The actual sections should come first, though (a la http://eteq.github.com/astropy/vo/index.html ). (See also my comment on this in #209).
astrofrog commentedon Jun 1, 2012
@eteq - I agree that the functions/methods could still appear in the TOC, and I guess they will be constrained to the API section under the new documentation layout rules anyway. And to answer your question - feel free to implement the shortening of the titles in automodapi.
eteq commentedon Jun 2, 2012
FYI, making this change would conflict with #217, so I'll deal with it there (or at least wait for it to be merged)
Note: the way to do this is replace the
{{ fullname }}title at the top of the package to{{ objname }}for all of the autosummary templates.short names for autosummary-generated pages - closes astropy#243
short names for autosummary-generated pages - closes astropy#243
short names for autosummary-generated pages - closes astropy#243
Merge pull request astropy#243 from katrinleinweber/resolve-DOIs-secu…