Needs astropy/ci-helpers#61 to be merged.

@bsipocz - above, you noted this needed ci-helpers 61 to get merged, which has happened. I restarted the sphinx build in case, but maybe this needs to be rebased?

@bsipocz - looking better at the failure, I see that you need to make a change in .travis.yml similar to what @astrofrog had told me in the context of #4456, namely use beautifulsoup4.

Looking at this again, I have no idea why I linked this to astropy/ci-helpers#61, it should have been astropy/astropy-helpers#216 instead (it's needed to be able to resolve the problematic intersphinx references).
And you're right with beautifulsoup4 issue, I'm fixing it with the new commit and rebase.

(Note that I've cancelled appveyor to ease up a bit of the congestion, none of the changes in this PR has an effect on appveyor).

I milestoned this as 1.2 as I mentioned in astropy/astropy-helpers#216, although if there's a strong reason to get it in sooner we can try for something in 1.1.x

One other complication for this: right now one of the reasons for testing the doc builds with 2.x is that readthedocs, which in some sense is the "canonical" copy of the docs, uses 2.x. We could change that, but it looks like you can only change the python version used to build RTD on a "whole project" basis. So we couldn't e.g. have v1.0.x be on Python 2.x, but 1.2.x be on 3.x.

So what that makes me think is that we might have to wait until Astropy 2.0 (when we can retire the 1.0 build) to switch RTD to 3.x. In that case, we probably still want to test the 2.x build_sphinx with travis. Or we could do both?

@eteq - is it a problem to build 1.0.x documentation on python3?

@eteq - Either way seems fine I think (having it in v2.0, or try to port this pack to v1.0.x as supporting py3 is not a new feature).

However I feel it is being wasted travis time to build both py2 and py3 docs on travis.

Agreed that we should not build both! Indeed, in principle, I think it would be nice to reduce the tests run for PRs to a smaller subset, and only run a full suite before actual merging. But not sure that is possible (and easy).

@mhvk - I think it shouldn't be too difficult to add an env variable to ci-helpers that makes sure that the tests are only run when the commit message contains a certain keyword (e.g. Merge pull request (as that is included in all PR merge, or something like [full tests] or [full suite], etc).

Rebased, but cancelled the CI builds as this requires the helpers PR first.

I've restarted this since the helpers PR got merged (although I'm not sure if we've made a new helpers release since, so this might not help)

Could we rebase this and rerun the test suite? It is still running Numpy 1.6 tests, so obviously has not picked up the recent removal of 1.6 (#4784).

@astrofrog - as far as I know there wasn't any new helpers release. Do you want me to add the current helpers master in this PR? I don't see any controversial in it as this PR milestoned as 1.2 and it's clear that there will be a helpers release before releasing 1.2.

@pllim - There isn't any changes that should brake with 1.6 included, but I'll rebase once the helpers issue above is solved with either option.

Added the updated helpers master, and rebased. I expect it to pass (except some triviality that possibly got merged in the last 3 weeks since I last tested this locally).

Looks like it all works now! I'd merge were it not for #4556 (comment): do we have to backport this so that older versions generate consistent documentation? @eteq?

Good point @mhvk. I'm trying to cherry-pick this on top of v1.0.x.

This looks good to me - however, to be clear about this, once we also update RTD (which we should do as soon as this is merged, otherwise some links will break) all API links for Python will now link to the Python 3 docs. This is fine by me, but I'd like to get a final OK from @eteq and @taldcroft before merging.

collections.Mapping is one of the problematic cases and a usage of it got merged recently, thus this PR now needs a rebase and then a helpers version where astropy/astropy-helpers#238 is merged.

This is now rebased and should pass.

👍 on linking to Python 3 docs.

👍

I'm 👎 on backporting this to 1.0.x - an LTS should not suddenly change what version of python it's docs are built against. Even though there's not a real connection involved on the code side, users who follow those doc links will probably interpret it that way.

So given you can't change RTD's python version for one build and not another, I think it's best to merge this, but without the .travis.yml change for 1.2 - I think it's important the RTD and travis versions match (because otherwise PRs will unknowingly break the RTD build). Perhaps by 1.3 there'll be a way to tell RTD to build specific versions with specific pythons... Or if not, we can switch over at the next LTS.

Oh, but I'm 👍 to merging it and backporting to 1.2 (with the small tweak of not changing the sphinx build on travis)

@eteq - I don't really see the problem for LTS; all that really changes is that the rare links for exceptions etc. now point to python3. That will mostly not matter, but to the extent it does, it is just as (ever so slightly) helpful to those working with python3 as it is (ever so slightly) unhelpful to those still on python2. And to give the latter a slight push to start moving to python3 is probably a good thing.

I'm going to check whether this backports cleanly to 1.0.x and whether the 1.0.x docs then build in Python 3 without warnings.

Here are some findings/thoughts:

• The PR here can be backported mostly cleanly (with a few exceptions) to the 1.0.x branch. Once I do that, I get only 3 warnings, so it certainly seems possible to fix that.
• If we want to support building the 1.0.x docs with Python 3, we will need to backport any astropy-helpers changes that are needed for this to work properly to the astropy-helpers 1.0.x series. Currently, when I backported this PR to 1.0.x locally, I just updated astropy-helpers to the absolute latest master.
• I think we should do the switch to Python 3 on RTD after the release so that we can deal with things step by step. Note that RTD will not stop serving existing docs, so once we make the switch on RTD to Python 3, only new docs will need to be build-able. This suggests to me the following timeline:
  1. Merge this PR and keep Travis on Python 2.7
  2. Go ahead with the 1.2 and 1.0.10 releases
  3. Switch Travis and RTD to build the docs with Python 3. At this point, new latest builds will start building with Python 3, and future 1.2.x builds will also be fine since the 1.2.x branch includes the changes here.
  4. Backport any required changes for the docs to build to astropy-helpers 1.0.x, and release a new version of the helpers
  5. Update the 1.0.x branch of astropy core to the latest astropy-helpers and do whatever fixes are needed to get it building without errors on Python 3
  6. Carry out a new 1.0.x release, which will now build correctly on RTD

I've removed the commit that changes the travis from 2.7 to 3.5, and will open a separate new PR for it once this one is merged.

With the removal of .travis.yml I think this PR is all OK, so I'll merge it. @bsipocz - could you indeed open a new PR, maybe linking to or even including the list @astrofrog made above?

@mhvk - thanks for merging this! However, I noticed the following issue with this pull request:

• Changelog entry not present (or pull request number missing) and neither the Affects-dev nor the no-changelog-entry-needed label are set

Would it be possible to fix this? Thanks!

This is an experimental bot being written by @astrofrog - let me know if the message above is incorrect!

🎉 @mhvk - Thanks for the merge, I'll open a PR.