Documentation incomplete

[stsci-hack]

The current instructions provided in the README file point the user to a sample 'setup.py' and 'setup.cfg' file to see how to include this package in those files. Unfortunately, this is not sufficient for successfully adding this package as a submodule to a project. A user wanting to take advantage of astropy-helpers needs an step-by-step example of all the operations which need to be implemented in order to add this package as a submodule to another package.

In addition, the only description (as incomplete as it is) for what functionality this package provides can only be found in the APE originally used to approve the implementation of this package. This is not directly associated with this package, and really takes a concerted effort by the user to even find. Additional documentation really needs to be added to describe what this package can do and, more importantly, why anyone would want to use this package in the first place. The README hints at only some of the benefits this package provides when used.

[pllim]

The usual way this submodule gets into a package is via https://github.com/astropy/package-template . Doesn't mean the doc here can't be improved though.

[astrofrog]

See also #7

[stscicrawford]

I've just run into this problem again and it is a bit worse now due to the older documentation for the manual creation of the template package seem to no longer exist. I'll see if I can commit something minimal today

[bsipocz]

👍 to revive the docs for manual creation and update, I would have thought that we kept that one in the template docs.

(not a solution but a workaround @stscicrawford: http://docs.astropy.org/en/v2.0.5/development/astropy-package-template.html)

[hamogu]

Just a note: With the discussion in #417, #418, #419, and #420 this issue might solve itself or at least become much easier, depending on how much functionality will be removed form astropy-helpers and what the future strategy to bundle it will be.

[bsipocz]

@hamogu - I love when issues resolves themselves if you let them rot there long enough. (not ideal, but still better than when they come back all the time to haunt you...)

[astrofrog]

I think this is addressed by #418