Make sphinx-astropy an explicit dependency for docs build

[bsipocz]

Packages relying on astropy-helpers to provide docs building infrastructure should make sphinx-astropy an explicit dependency. Being cleaver and building it and the full dependency three as eggs proved to be problematic when those dependencies start to introduce some version restrictions (e.g. mpl for python, and numpydoc for sphinx) See e.g., #462, #463, #465, etc.

And in addition building the eggs for all those dependencies is the least efficient way to install them (#471)

Now it is a good time to make this change, before the actual v3.2 release.

cc @astrofrog

[astrofrog]

I personally agree, I think it's reasonable to just crash and tell users that sphinx-astropy is needed if it's not installed.

[pllim]

Where exactly do you want that message? There is already this here

astropy-helpers/astropy_helpers/sphinx/conf.py

Line 5 in 222e6b5

warnings.warn("Note that astropy_helpers.sphinx.conf is deprecated - use sphinx_astropy.conf instead")

[astrofrog]

I think we should also raise an error here:

https://github.com/astropy/astropy-helpers/blob/master/astropy_helpers/commands/build_sphinx.py#L192

just to be on the safe side (instead of calling ensure_....

[bsipocz]

I'll open a PR for this at the end of the today.

[saimn]

And we also have now an explicit dependency with sphinx-asdf, so installing sphinx-astropy under the hood is not enough to build the docs anyway.

[astrofrog]

Arguably we could make sphinx-asdf a dependency of sphinx-astropy, but let's fix its major performance issues first!

[bsipocz]

This was really done for packages other than astropy who use the template and the helpers but not necessarily know what goes on under the hood. astropy always had the explicit dependency on sphinx-astropy listed in setup.py/setup.cfg.

[bsipocz]

Addressed by #474 (and now I realized "address" is not a magic word, so that PR didn't close this issue automatically).