Doc build path varies between setup.py build_docs and make html #4133

saimn · 2015-09-08T13:43:34Z

When using a classic make html inside the doc directory, the doc is build in docs/_build/html.
But when using python setup.py build_docs as stated in the install page the output path is build/sphinx/html which is quite confusing. I had an old version of the doc in the first directory, which was not updated when running build_docs.

The build/sphinx/ path seems to come from sphinx.setup_command.BuildDoc, maybe it could modified in AstropyBuildSphinx to docs/_build/ and have the same output drectory as make html ?

Futhermore make html is broken for me with Python 3.4. This is related to #2532, but in my case, with python 3 and an install in develop mode, import astropy_helpers works because the astropy_helpers directory is inside the astropy one pointed by the .egg-link, but it returns an invalid module:

~/lib/astropy/docs docs
(astropy)❯ python -c 'import astropy_helpers; print(astropy_helpers)'
<module 'astropy_helpers' (namespace)>

With the following patch I can use make html in the docs directory, but it is just more hackish :

diff --git a/docs/conf.py b/docs/conf.py
index 11192b9..9ae24ea 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -26,7 +26,7 @@
 # be accessible, and the documentation will not build correctly.

 try:
-    import astropy_helpers
+    from astropy_helpers.sphinx.conf import *
 except ImportError:
     # Building from inside the docs/ directory?
     import os
@@ -36,6 +36,9 @@ except ImportError:
         if os.path.isdir(a_h_path):
             sys.path.insert(1, a_h_path)

+    if 'astropy_helpers' in sys.modules:
+        del sys.modules['astropy_helpers']
+
     # If that doesn't work trying to import from astropy_helpers below will
     # still blow up

Depending on the build method the output directory is not the same: - `docs/_build/html` with `make html` in the docs directory - `build/sphinx/html` with `setup.py build_docs`

embray · 2015-09-09T15:04:56Z

I've noticed also that that changed, but I'm not entirely sure why it did. I don't think it was intentional, and it may be something that changed actually in Sphinx. I agree it's confusing, and would rather it just go to docs/_build (or alternatively, "build/docs", but not "build/sphinx" since that's hard to find...).

I'm not sure about running make html directly though. I think that there are reasons in the past that I've said it won't work, but I can't articulate them at the moment. If you want to have the submodule of astropy_helpers on your path during development you should:

$ cd astropy_helpers
$ ./setup.py develop

saimn · 2015-09-10T07:21:31Z

I have no preference between the two ways to build the docs, but if setup.py build_docs is the way to go then the Makefile should probably be removed to avoid confusion (especially if this way is broken).

embray · 2015-09-10T16:07:49Z

Looking at the build_sphinx command implementation, it seems to also assume that the docs are going to be output to docs/_build. I swear it used to do that too. So I suspect something changed in Sphinx. That would be an issue for astropy-helpers though.

I'd be okay with removing the makefile--I never use it and see no reason to have more than one way to do it. I need to double check whether or not that's necessary for readthedocs though. It might be.

embray · 2015-09-10T16:09:17Z

To clarify, all the makefile itself really does is run the sphinx-build command with the correct options. Whereas the advantage to ./setup.py build_docs is that it makes sure all dependencies can be imported, and that the package is built and fully importable.

hamogu · 2016-06-15T00:41:04Z

I've in the past used the makefile when I needed to debug sphinx failures. Sphinx can (with the right options) drop you into the debugger when it encounters an error. Could I do that with python setup.py build_sphinx, too?

saimn · 2016-06-15T07:12:02Z

@hamogu - it seems setup.py build_docs does not have the pdb option, though it should easy to add. And the Makefile uses the sphinx-build command, so you could still use this command directly if needed.

eteq · 2016-07-05T20:48:16Z

Just realized the origin of this problem: build_docs is not the intended command. build_sphinx is the correct one. Currently build_docs is aliased to build_sphinx, but setup.cfg does not have a section for build_docs like it does for build_sphinx, and apparently the setup script doesn't pick up the setup.cfg section for build_sphinx if you use build_docs even though it's an alias.

So the install docs are just wrong, first of all. But also we should either add a build_docs section to setup.cfg or just remove/disable build_docs with some kind of redirection.

astrofrog · 2016-07-05T20:54:08Z

Ah, I think we switched to recommending build_docs in #3924?

eteq · 2016-07-05T20:57:00Z

Ohh, didn't know that. Guess I'm the dinosaur, then. But then it's been broken since then because it's definitely wrong in a lot of ways to be going into build/sphinx/..., so we should add a [build_docs] section to setup.cfg with the same content as the [build_sphinx] section.

astrofrog · 2016-07-05T20:58:18Z

Ahem:

😉

astrofrog · 2016-07-05T20:59:13Z

But yes indeed, we need to update setup.cfg - thanks for spotting the issue!

eteq · 2016-07-05T20:59:17Z

... maybe that's that other @eteq that keeps merging things when I'm not looking? ;)

astrofrog · 2016-07-05T20:59:29Z

Ah, you have a sentient bot too?

eteq · 2016-07-05T21:04:06Z

saimn · 2016-07-06T06:57:56Z

Oh, good catch @eteq !

saimn · 2016-07-06T06:58:21Z

Also, from the discussion above, we should remove the Makefile and have only one way to build the docs.

eteq · 2016-07-06T21:53:47Z

@saimn - personally I'm +0 to removing the makefile - I don't really care about it, but I think some others expect it. But I see your point that it is clearly causing some confusion. Maybe make a separate issue/PR to do that and we can decide there?

(this issue was auto-closed by #5156, which fixed the underlying problem of the setup.cfg not including build_docs)

`make html` does not work on Python 3, and there should be only one way to build the docs (`setup.py build_docs`) and avoid to confuse users: Exception occurred: File "conf.py", line 43, in <module> from astropy_helpers.sphinx.conf import * ImportError: No module named 'astropy_helpers.sphinx' Ref astropy#4133, astropy#2532

saimn · 2016-07-07T10:23:06Z

@eteq - See #5161. Using make html is usually the way to build a sphinx documentation, so it's better to remove it to avoid confusion.

Update doc build path.

3f74fad

Depending on the build method the output directory is not the same: - `docs/_build/html` with `make html` in the docs directory - `build/sphinx/html` with `setup.py build_docs`

embray added Docs build labels Sep 9, 2015

embray added the zzz 💤 astropy-helpers archived: PRs and issues related to astropy-helpers label Sep 10, 2015

embray force-pushed the master branch from 63540e0 to 34f4c29 Compare October 5, 2015 21:18

adrn mentioned this pull request Jul 5, 2016

Fix build_docs build path #5156

Merged

eteq closed this in #5156 Jul 6, 2016

saimn mentioned this pull request Jul 7, 2016

Remove doc Makefile. #5161

Closed

saimn deleted the docs branch January 23, 2017 13:47

saimn mentioned this pull request Jan 23, 2017

Update default locations for doc build in docs #5725

Closed

Uh oh!

Doc build path varies between setup.py build_docs and make html #4133

Doc build path varies between setup.py build_docs and make html #4133

Uh oh!

Conversation

saimn commented Sep 8, 2015

Uh oh!

embray commented Sep 9, 2015

Uh oh!

saimn commented Sep 10, 2015

Uh oh!

embray commented Sep 10, 2015

Uh oh!

embray commented Sep 10, 2015

Uh oh!

hamogu commented Jun 15, 2016

Uh oh!

saimn commented Jun 15, 2016

Uh oh!

eteq commented Jul 5, 2016

Uh oh!

astrofrog commented Jul 5, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eteq commented Jul 5, 2016

Uh oh!

astrofrog commented Jul 5, 2016

Uh oh!

astrofrog commented Jul 5, 2016

Uh oh!

eteq commented Jul 5, 2016

Uh oh!

astrofrog commented Jul 5, 2016

Uh oh!

eteq commented Jul 5, 2016

Uh oh!

saimn commented Jul 6, 2016

Uh oh!

saimn commented Jul 6, 2016

Uh oh!

eteq commented Jul 6, 2016

Uh oh!

saimn commented Jul 7, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

astrofrog commented Jul 5, 2016 •

edited

Loading