Add parameter doc to sunpy/sun/sun.py

[dstansby]

There is a lot of repetition here because all the methods take the same argument - I wasn't sure how to avoid just copy and pasting the same bit of text, so that's what I've done. If anyone else knows a better way to do this please let me know!

[dpshelio]

In pandas I've seen they use a dictionary with docstrings that they append to the functions that need it. Check this https://github.com/pandas-dev/pandas/blob/master/pandas/core/generic.py#L477 Maybe something could be done in here in a similar fashion, but I think that requires some extra thinking.

[Cadair]

I haven't tested it but I think this would work:

PARAMETER_DOCS = """
Parameters
---------------
...
""""

def add_parameter_docs(f):
    f.__doc__+= PARAMETER_DOCS
    return f

@add_parameter_docs
def sun_location(t='now'):
    """
    This does a thing.

    """

[nabobalis]

I just did that locally.

It looks a bit off but I can't figure out why.

vs

Edit: Fixed it but it created a warning in the doc build. #ohwell

[Cadair]

this should be six.string_types

[nabobalis]

OH YEAH IN THIS CRAZY WORLD

[nabobalis]

We should move the decorator somewhere else just incase we need it for the future.

[Cadair]

Yeah, we should refactor it into utils and let it take arguments. Maybe a prepend and append argument to the decorator?

We should merge this then open a separate issue for it.

[Cadair]

We could also make it do a .format on the docstring if a dictionary is provided as an argument to the decorator.

[nabobalis]

Looks like I messed up.

/home/travis/build/sunpy/sunpy/build/lib.linux-x86_64-3.6/sunpy/sun/sun.py:docstring of sunpy.sun.heliographic_solar_center:6: SEVERE: Unexpected section title.

Parameters
----------
/home/travis/build/sunpy/sunpy/build/lib.linux-x86_64-3.6/sunpy/sun/sun.py:docstring of sunpy.sun.solar_north:6: SEVERE: Unexpected section title.

Parameters
----------
/home/travis/build/sunpy/sunpy/build/lib.linux-x86_64-3.6/sunpy/sun/sun.py:docstring of sunpy.sun.sunearth_distance:6: ERROR: Unexpected indentation.
/home/travis/build/sunpy/sunpy/build/lib.linux-x86_64-3.6/sunpy/sun/sun.py:docstring of sunpy.sun.sunearth_distance:7: SEVERE: Unexpected section title.

I will fix these soon(TM)

[nabobalis]

Doc builds without problems now.