Add instructions to set up readthedocs

[cdeil]

Should we add instructions on how to set up documentation on readthedocs for astropy affiliated packages. We could mention that this is just one option and that the authors are free to put docs elsewhere.

Specifically I wanted to set up docs on readthedocs and didn't manage (but didn't investigate further yet): https://github.com/cdeil/crosstalk/issues/1

[eteq]

This is a good idea, but I'm not sure exactly where - my first instinct is in the package-template readme, but we could put it in the astropy documentation instead (along with #23 and #17 ?). @astrofrog - do you have any opinions on that?

[eteq]

Oh, and @cdeil - it turns out there are some key "gotchas" in RTD that are easy to miss. For the astropy core package, these are the most important things that took me a while to realize are necessary:

• You need to check "use virtualenv" and "Use system packages", otherwise a lot of crucial dependencies will be missing.
• You may need to use a pip requirements file to specify an astropy version. I'm not sure why, but sometimes that seems to help convince it to build the correct version of various dependencies.
• If you think it really should be working and it isn't , try the instructions at http://read-the-docs.readthedocs.org/en/latest/builds.html#deleting-a-stale-or-broken-build-environment ... that seems to just magically fix things about a third of the time, in my experience. (Sort of like hitting the reset button...)

[cdeil]

Thanks for the tips ... now that there's a pull request for sampy into astropy.vo I don't wont to create an affiliated package at the moment ... but if I want to in the future it would be nice if there are these little tips on how to make it work. I think the best would be for package-template readme to contain a short bullet point as a reminder and then the steps and tips could go into a howto_setup_readthedocs.

[eteq]

Hmm, I think it's better to avoid adding extra files to the package template (like a howto_setup_readthedocs) because that makes the readme even more complicated and also gives more opportunities for an affiliated package to forget to delete the file and be confused later. But I like the idea of a small bullet point in the main readme that points to more detailed instructions elsewhere.

[astrofrog]

I think this could live in the main Astropy docs.

[keflavich]

I vote for adding these instructions to the README in this package - that's where I went when setting up a package today, and I was surprised to see instructions for travis but not for readthedocs. The biggest pain is remembering @eteq's top gotcha about virtualenv + use system packages.

[keflavich]

Also, instructions for Mocking out modules should be included, e.g. including this in conf.py:

# read the docs mocks
import sys

class Mock(object):
    def __init__(self, *args, **kwargs):
        pass

    def __call__(self, *args, **kwargs):
        return Mock()

    @classmethod
    def __getattr__(cls, name):
        if name in ('__file__', '__path__'):
            return '/dev/null'
        elif name[0] == name[0].upper():
            return type(name, (), {})
        else:
            return Mock()

MOCK_MODULES = ['numpy']
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = Mock()

[cdeil]

There are some instructions now here: http://astropy.readthedocs.org/en/latest/development/affiliated-packages.html

Probably this should be put in a sub section so that it can be linked to.

@astrofrog @mwcraig Do you plan to restructure http://astropy.readthedocs.org/en/latest/development/affiliated-packages.html in the coming days or should I take a stab at it?

[mwcraig]

@Cdeil - realistically, I won't have a chance for several days, so please do go ahead.

[cdeil]

@astrofrog did this: http://astropy.readthedocs.org/en/latest/development/affiliated-packages.html#id1