astropy/astropy — pull request #219 by mdboom (2012-05-01 16:14:08+00:00)
Title: Convert VO documentation into the new organization

This is a first pass at converting the `io.vo` 's docs to use the new subpackage template as proposed in #218.

There are a few issues I ran into, and maybe @eteq or others know the answers. Let me know if it makes sense to create new issues for them.

1. The `io.vo` docs contain many links to the IOVA VOTable spec so that the reader can get more detail from the horse's mouth if desired. Previously, this was handled by putting a number of references in `docs/vo/references.txt` and including that from the top of every API doc. Now that most of the docstrings are on their own auto-generated pages, those links are no longer defined. It seems to me like we need a way to, from the automodapi directive, define some preamble to go at the top of every generated file. Or maybe there's another solution, but I'd like to avoid sprinkling these URLs all through the docstrings.

2. The convention that the summary table contains the first line of the docstring is often too limiting, particularly when you want to say:

```
Given an `~astropy.io.vo.tree.VOTable` instance, return the first `~astropy.io.vo.tree.Table` instance.
```

At the moment, I've just used lines much longer than 80 characters, but I'm wondering if the summarizer can't be convinced to use the first paragraph rather than the first line.

3. Sometimes I find myself wanting to document classes that are not made public, but are returned by the public API. For example, I have a function `get_converter` that returns one of many `Converter` subclasses. I don't want to expose these subclasses through `__all__`, since they shouldn't be instantiated directly, but I do want to document their methods. Any pointers?

4. It doesn't seem that class methods get documented. If you look at a Class page, for example `astropy.config.ConfigurationItem`, the summary for its `save` method is included in the table, but there is no link to the complete documentation for `save`.