Auto-generate API files

[weaverba137]

This PR closes #130, providing a mechanism to auto-generate Sphinx API files.

Examples:

• Generate doc/api.rst from scratch: python setup.py api
• Overwrite an existing doc/api.rst file: python setup.py api --overwrite
• Generate a new api file to compare with an existing file: python setup.py api --api doc/new_api.rst

I've tested this on desiutil itself, where it generated a document byte-for-byte identical to the existing api file, and also on desispec, where it found only minor differences.

[sbailey]

Nice!

How hard would it be to either add this as a pre-runner to "python setup.py build_sphinx", or otherwise add another command that would effectively be "python setup.py api --overwrite && python setup.py build_sphinx" and we would start using that instead of "build_sphinx"?

i.e. this is so nice at auto-generating the API, is there any reason why we wouldn't want to automatically do that instead of requiring us to remember to run "python setup.py api --overwrite" occasionally to make sure our api.rst is up-to-date? Or maybe include it in travis tests to flag if api.rst is out of date?

OK to merge as-is if these extensions are non-trivial, but otherwise this looks so good I'd like to automate its use if possible instead of requiring us to remember to use it.

[weaverba137]

I don't think we always want to automatically overwrite the doc/api.rst, which is why I included --overwrite and related options:

• Some API files may contain custom titles, text, or other metadata. The desispec api.rst file does.
• In a handful of cases, we might want not to include certain auto-detected modules. For example, desispec/pipeline/attic/workers.py.

[weaverba137]

I actually did replace the python setup.py test command in the past, and that was somewhat painful. I think the best practice is to run this as a check when tagging a new version, or when adding several new modules. Or to just generate the file for the first time for a brand-new package.

[sbailey]

OK, sounds good. Thanks for the followup explanations. Merging now.