[Feature] Add docs about neo-python

[localhuman]

This is by no means finished, but a WIP here: http://neo-python.readthedocs.io/en/latest/index.html

Currently working out of the feature-docs branch

[localhuman]

• Add in docstrings to all methods/modules etc
• Fill in docstrings with more than boilerplate
• Create sphinx documentation
• Publish to readthedocs.io

[ixje]

Any good document that shows how the docstrings should look for sphinx compatibility? I find there website a bit messy. Perhaps some samples how to document function parameters, return type would be nice.

[metachris]

I personally like the Google style docstrings:

• http://www.sphinx-doc.org/en/stable/ext/example_google.html
• http://google.github.io/styleguide/pyguide.html?showone=Comments#Comments

This is how it's done in neo-boa:

• Docstrings: https://github.com/CityOfZion/neo-boa/blob/master/boa/compiler.py
• Generated docs: http://neo-boa.readthedocs.io/en/latest/_modules/boa/compiler.html#Compiler

Here is another example with:

• Docstrings: https://github.com/metachris/logzero/blob/master/logzero/__init__.py#L379
• Generated docs: https://logzero.readthedocs.io/en/latest/#i-logzero-logfile

[ixje]

I started converting #74 to rST format as requested by @localhuman here. Unfortunately also that standard leaves room for interpretation / free will. Before having to edit everything a 3rd time I'd like to get to an agreement on how to document the following:

• multiple return types
• exceptions
• notes

multiple return types

Example with current Sphinx Napoleon format:

"""
Change the password used to protect the private key.

    Args:
        password_old (str): the current password used to encrypt the private key.
        password_new (str): the new to be used password to encrypt the private key.

    Returns:
        bool: False, if the old password does not match the current saved password.
        None: If successfully changed the password.

"""

Attempt 1:

        :return: False, if the old password does not match the current saved password. None, If succesfully changed the password.
        :rtype: bool, None

Attempt 2 (suggested here):
Note: this drops the :rtype:

    :return: 
        bool False if the old password does not match the current saved password. 
        None None If successfully changed the password.

Exception documentation

Example:

        """
        Retrieve the script_hash from an address.

        Args:
            address (str): a base58 encoded address.

        Raises:
            ValuesError: if an invalid address is supplied or the coin version is incorrect.
            Exception: if the address checksum fails.

        Returns:
            UInt160: script hash

        """

PyCharm format:

:raises: :exc:ExceptionType

   :raises: :exc: `ValueError` if an invalid address is supplied or the coin version is incorrect.
   :raises: :exc: `Exception` if the address checksum fails.

Note that I'm uncertain here if I should repeat :raises: and if it's ok to add the description behind it.

Sphynx doc example

   :raises ValueError: if an invalid address is supplied or the coin version is incorrect.
   :raises Exception: if the address checksum fails.

Notes

Current:

"""
Add a watch only address to the wallet.
  
Args:
    script_hash (UInt160): a bytearray (len 20) representing the public key.

Returns:
    None
 
Note:
    Prints a warning to the console if the address already exists in the wallet.
 
"""

Attempt (ok?)

        """
        Add a watch only address to the wallet.

        :param script_hash: a bytearray (len 20) representing the public key.
        :type script_hash: UInt160
        .. note:: Prints a warning to the console if the address already exists in the wallet.
        :return:
        """

[ixje]

It's probably good to say we settled on using Google's docstring notation and no longer the rST format discussed just above.

[localhuman]

This is complete, though further documentation would never hurt.