What about removing only the html part from the makefile rather than the whole file?
E.g. I use make clean quite often when in need of a clean docs directory.

Indeed, clean can be useful ! Removing the files was the quickest solution ;), but I put back the useful rules. Any other rules that might be used ?

😱 😱 😱

I always use make html and make clean...

😱 😱 😱

@pllim - So you don't use Python 3 ? 😉

why does make html not work under python 3?

@Cadair - IIRC, the Sphinx config file needs to import astropy_helpers, which is not in the Python path. A workaround was added in #2532, but it does not work on Python 3 (#4133). There must be a way to fix it, but build_docs already takes care of doing this.

isn't this going to be an issue on RTD? If we ever want that to move over to Python 3?

Hmm, there is an action item to do just that in #5135...

RTD uses sphinx-build directly, so no issue with the Makefile, but it could indeed suffer from the astropy_helpers import issue.

well all make html does is call sphinx-build right?

@Cadair - Yes, indeed.

I thought the py 3 problem was that it doesn't run the "fixers" to convert the py2 codebase to py3?

More generally, using make html instead of python setup.py build_docs requires that you make sure you have the latest dev version of the package you're building docs for installed to get the API docs... That's why I always use the latter, anyway.

(That is to say, I'm 👍 to this change if it doesn't break anything, and the passing tests make me thing it doesn't)

I don't know about a "fixers" issue, you mean with 2to3 ?
The issue from #4133 is that astropy_helpers must be importable, so #2532 added a workaround in the conf.py file, which doesn't work on py3. Otherwise it is possible to install astropy_helpers, but it requires an extra step. And build_docs takes care of this.

Not sure if I understand... I have no problem building the latest dev docs on Python 3. What is the exact commands to reproduce the problem?

@pllim : did you install astropy_helpers ?

~/Dev/astro/astropy/docs master
(test-astropy) ❯ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.4.1

Exception occurred:
  File "conf.py", line 43, in <module>
    from astropy_helpers.sphinx.conf import *
ImportError: No module named 'astropy_helpers.sphinx'
The full traceback has been saved in /tmp/simon/sphinx-err-gef3hku2.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [Makefile:44: html] Error 1

In the upper level, I did a git submodule update --init to include astropy_helpers, yes.

@pllim - That doesn't install astropy_helpers, can you import it from a python shell ?

Yes, I can. But I don't remember installing it... Here is some info:

Python 3.5.1 |Continuum Analytics, Inc.| (default, Dec  7 2015, 11:16:01) 
[GCC 4.4.7 20120313 (Red Hat 4.4.7-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import astropy_helpers
>>> astropy_helpers
<module 'astropy_helpers' (namespace)>
>>> astropy_helpers.__path__
_NamespacePath(['/path/to/source/astropy/astropy_helpers'])

Ah no, ok, it is specific to the develop mode ! Sorry, I didn't remember all the details of #4133 ...

To explain a bit more:

• When installed "normally" (not develop mode), from the docs directory, you can't import astropy_helpers, so you go to the except block introduced in astropy_helpers not found in "cd docs; make html" #2532, which adds the root directory to the python path to make it possible to import astropy_helpers.
• When using develop mode, you have an astropy.egg-link which points to the root directory of astropy. Because of this, it is possible to import astropy_helpers, but it gives the parent directory, not the inner one which contains the python modules, so it fails later.

So , I will close this PR as the Makefile seems useful ;-). I could try also try to make the import work in the Makefile for the develop mode, but I don't think it is worth spending time on this.