Improved Documentation

[tjdevries]

We should add a readthedocs website for documentation.

And then we can generate it from the classes. This should be followed with some examples in each class or something.

I tried adding some in the elementvariable class, since now it's a bit more complex the things you can do with it. This would be helpful when you're first starting out using the module.

[sprout42]

gasp!

yeah good examples and docs are desperately needed. Presumably add them in so that they can be of the proper form to be up on https://readthedocs.org/

[tjdevries]

I'll get a chance to do this over the weekend I think.

[sprout42]

oh sweet! that'd be super helpful.

[tjdevries]

What style do you want to do the function documentation in?

There's google, sphinx.... etc. Do you have a preference?

[sprout42]

Personally I like the way sphinx looks... but if you'd rather do something different that's fine with me. I've never actually written sphinx compliant docs before so I don't know if it's super annoying or not.

[tjdevries]

Here's an example of google style:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

and here's the sphinx one

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    :param arg1: description of arg1
    :type arg1: int
    :param arg2: desc....
    :type arg2: str
    :returns bool:
    """
    return True

I'm fine doing either way. I've done Google style in the past, but I'd be up to learn the sphinx one.

[sprout42]

The google style is more aesthetically pleasing to me. But I am cool either way.

[tjdevries]

Okay, let's do the google one. I agree it is more readable.

[tjdevries]

Actually, I found this sphinx plugin: https://github.com/daviskirk/sphinx-autodoc-napoleon-typehints

It makes the regular sphinx one look fine, and I think it's easier to get sphinx to work with that style. So if you like that, we'll go with regular sphinx style, but using real type hinting, so that we don't have to specify that in the description.

[sprout42]

sounds good to me