Add Sphinx documentation

[cliffckerr]

Choices are:

• NumPy docstrings (nice, but too verbose?): https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy
• Google docstrings (my favorite?): https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
• Original Sphinx docstrings (not my favorite, hard to read in plain text): https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html

Example (still a little sparse) from parestlib/binnts.py:

def knn(test, train, values, k=3, nbootstrap=10, weighted=False, quantiles=None):
    '''
    Perform k-nearest-neighbors estimation.

    Args:
        test (NxP float): Test set: N points in P-dimensional space for which the values need to be estimated
        train (MxP float): Training set: M pointsin P-dimensional space for which the values are known
        values (M float): Values to match the training data
        k (int): Number of nearest neighbors; default 3
        nbootstrap (int): Number of bootstrap iterations; default 10
        weighted (bool): Whether or not neighbors should be weighted by distance; default False
        quantiles (2 int): Pair of quantiles for bound estimation; default IQR [0.25, 0.75]

    Returns:
        output (objdict): An object with best, low, and high estimates of the value at each test point
    '''

Would also be good to implement examples + doctests...

[JSchripsema-IDM]

We adopted Google style docstrings in IDM-Tools, so that is my preference as well. I can get a stubbed out docset set up in the repo. Because this is outside the IDM org, it presents some difficulties in building/hosting automatically.

[cliffckerr]

Thanks @JSchripsema-IDM . I think what would be most helpful would be a best attempt to write each docstring. Hopefully the code is transparent enough that many or even most parameters are clear from reading through the code, but if not, maybe flag them somehow and @daniel-klein or I can fill them in. If needed, @RomeshA might be able to help get the docs building/hosting set up (he did https://atomica.tools/docs/master/index.html, which is a more comprehensive version of what would be great to have here); I'm imagining parestlib.github.io but there are many other choices.

[JSchripsema-IDM]

We use Bamboo to automatically build and then push the docs to gh-pages in the Documentation repo, but are early in the process of moving everything to Read the Docs for building/hosting (I believe the repo will have to be part of the IDM org for that to work). For now, it may make the most sense to build manually and push to the gh-pages branch of this repo. After that is done and IDM-Tools has been released, we can discuss the long-term plan.

[cliffckerr]

@JSchripsema-IDM Thinking about this now and talking to @daniel-klein, the code is probably still in too much flux for it to be worthwhile writing comprehensive documentation now. Will reopen this issue once it's ready though -- thanks! cc @RomeshA