I made a table of the remaining broken links with this in place: https://gist.github.com/astrofrog/7213e27ae31b1a36464f

and I've already fixed some of those, will open a PR in a few minutes.

@bsipocz - just for info, I fixed a few links, but I'm happy to rebase later. I also started adding exceptions for the numpy docstrings.

I've also opened a PR (#2509) with the finish packages (units and utils).
Have some more stuff in these files, but I haven't double checked or fixed everything.

(astropy-dev)bsipocz@kecske:~/munka/astropy/devel/astropy$ git stash show stash@{1} 
 astropy/convolution/convolve.py       | 91 +++++++++++++++++------------------
 astropy/io/fits/hdu/compressed.py     |  2 +-
 astropy/io/fits/hdu/image.py          |  2 +-
 astropy/modeling/fitting.py           | 72 ++++++++++++++-------------
 astropy/modeling/functional_models.py |  2 +-
 astropy/units/astrophys.py            |  6 +--
 astropy/units/core.py                 |  4 +-
 docs/conf.py                          |  2 +
 8 files changed, 93 insertions(+), 88 deletions(-)

@bsipocz - does it make sense for me to merge this once it passes, in case you want to add more commits to #2509?

Either case.
I'm not sure I can work more on this today, so either I commit everything I have to #2509 now or you merge it, and I open a new PR when I have more finished stuff and rebase it to your fixes.

@bsipocz - ok, I'll merge #2509 once reviewed and passing, and just open a new PR once you have time. Thanks for all your work on this!

@bsipocz - I think we should wait for #2507 and #2513 to be merged before working much more on this, since they will remove links to many non-existent functions.

I now updated the gist, there are ~200 warnings left: https://gist.github.com/astrofrog/7213e27ae31b1a36464f

We shouldn't touch the coordinates ones, so that leaves 160 or so warnings.

@bsipocz - if you do want to fix any more, please work from my branch and open a PR against my branch, since the contents of this PR will already reduce the number of warnings.

I'm working on some more fixes

@astrofrog - sorry, I couldn't figure out yet how to do a commit or PR in this branch. I guess I need to create a new branch and then git pull git://github.com/astrofrog/astropy.git? But then I end up with weird merge conflicts.
Or should I do this totally separated from my current astropy repo?

@bsipocz - the easiest way to do it is:

git remote add astrofrog git://github.com/astrofrog/astropy.git
git fetch astrofrog
git checkout astrofrog/nitpick-options
git checkout -b more-fixes  # or whatever branch name you want
<make changes, commit>
git push origin more-fixes

Then open a PR as usual but when you create the PR you have the option of editing where the PR is made to, and choose astrofrog/master instead of astropy/master. Any luck?

I've updated the gist at https://gist.github.com/astrofrog/7213e27ae31b1a36464f - there are no 150 links to fix, around 50 of which are related to coordinates (so we shouldn't touch those).

Some of the table/column methods are also not showing in the API docs (#2510) so we can't really fix that yet.

@eteq - this PR re-enables the use of intersphinx on Travis. It seems to work fine and is required if we turn on nitpick=True as done in this PR. Is there a strong case for leaving it off?

@mdboom - some of the base classes have to be listed in the nitpick-exceptions file in this PR (https://github.com/astropy/astropy/pull/2508/files#diff-12) since they are not in the public API. Since you looked into the base class links a little while back and fixed all the ones that could be fixed, do you think this is a reasonable approach?

The smart resolver can be made smarter about private classes and methods -- I think it's fine to assume that private classes and methods won't be in the docs, therefore we can ignore broken references to them outright. I've filed a PR against this for that. Over time, there are probably other classes in the nitpick-ignore list that should be explicity privatized and could be removed from the nitpick ignore list then, but that's for subsequent work, IMHO.

@mdboom - perfect, thanks! I agree that we should either explicitly privatize the remaining base classes or add them to the docs (though I agree it can wait).

@astrofrog - I think the reason why we turned it off on travis is because some of the intersphinx repos are not reliably on. That is, transitent failure in any of the intersphinx repos get turned into sphinx warnings, which makes travis indicate the build failed. So if we turn it back on, that just means we may get more red herring failures in the Travis sphinx build.

@eteq - hmm, in that case we won't be able to enable the nitpicky mode by default on Travis :-/ There is of course one option which is to mirror the objects.inv files ourselves, but not ideal. We could also make it that we use our versions only if run from Travis. Again, not ideal. Any ideas?

It might be possible to instead actually catch those particular errors and have them not count as "failing" on travis... although I'm not sure offhand how easy that will be.

Another option is to just turn it on and hope for the best. It might be that things have improved and the sites we turned it off for are no longer as unstable...? Or, from the other point of view, we already have a number of "random" test failures that we've just come to accept, and this might now be less often than those...

Ok - let's see if the failures happen while we work on this PR. It's not finished yet, so there will be a number of builds before we are done.

Is it me screwing up my copy of this branch, or indeed something happened with the inheritance diagrams? Local warnings are back at the 500+ level.

@bsipocz - huh, yes, indeed. For some reason @MBDOOM's commits disappeared from this branch. Checking.

Ok, something went wrong here... Investigating.

@bsipocz - I need to check, but it may be that the inheritance diagram fixes were not back-ported to the astropy-helpers.

@bsipocz - we will need astropy/astropy-helpers#6 to be merged to get rid of the warnings again.

Ohh, well. I have the feeling one can never get rid of all the warnings, a few will always pop up from unexpected places :)
Thanks for figuring it out where they were coming from.

I'm going to go ahead and merge if Travis passes since it's hard to keep up with all the rebasing. In any case, the only potentially controversial change is setting nitpick=True by default, which can easily be changed to False if needed (though I think it should be true to ensure that the docs keep a high standard of quality).

Thanks for all your help @bsipocz!

Thanks for the work on this. I haven't been following closely but are there are hints for doc authors to avoid having problems? Maybe a top-3 list of mistakes that were fixed? I guess it is pretty important now for people submitting PRs to run tests via python setup.py test [-P packagename] to fix docs locally before pushing to github.

I think one of the top 3 is using single backticks to refer to parameters and attributes rather than using double backticks.

@taldcroft - actually people should really run python setup.py build_sphinx -w since that is what catches the warnings. I agree with @bsipocz about one of the top threes. Another is to refer to classes/methods/functions in single ticks without referring to the full path.

I know this is way late, but I have no objections, @astrofrog 😉 - thanks for the work, both @astrofrog and @bsipocz !

@astrofrog, @eteq - what do you think about including the nitpick modifications of docs/conf.py and the exception file in the package-template/astropy_helpers? Broken links are reappearing in the affiliated packages like they did in astropy, having this feature would be quite beneficial there, too.

Should I open an issue/PR for it?

@bsipocz: That's a good idea: any "hard procedural problems" we're solving in astropy, we should make available to affiliated packages. However, as I think we're learning about a lot of features in astropy_helpers etc. lately, we should make this "opt-in", so that affiliated packages that want to devote the effort to making things perfect and clean can, and those without the time/inclination right now can put it off.

I agree with @mdboom here, @bsipocz. It should be in the helpers, but as an optional feature. I could see either opt-in or opt-out, bit of opt-out it should be very obvious how to do it (like with instructions printed as part of the warnings that cone out)

Well, then I'll look into this later this week.