Add Documentation (#125)

Add sphinx docs with readthedocs integration.

Docs can be built locally with `poe docs`.

docs/quick-start.rst

@@ -0,0 +1,192 @@
+Getting Started
+===============
+
+Installation
+++++++++++++
+
+Installation from PyPI is as simple as running:
+
+.. code-block:: sh
+
+    python3 -m pip install -U betterproto
+
+If you are using Windows, then the following should be used instead:
+
+.. code-block:: sh
+
+    py -3 -m pip install -U betterproto
+
+To include the protoc plugin, install betterproto[compiler] instead of betterproto,
+e.g.
+
+.. code-block:: sh
+
+    python3 -m pip install -U "betterproto[compiler]"
+
+Compiling proto files
++++++++++++++++++++++
+
+
+Given you installed the compiler and have a proto file, e.g ``example.proto``:
+
+.. code-block:: proto
+
+    syntax = "proto3";
+
+    package hello;
+
+    // Greeting represents a message you can tell a user.
+    message Greeting {
+      string message = 1;
+    }
+
+To compile the proto you would run the following:
+
+You can run the following to invoke protoc directly:
+
+.. code-block:: sh
+
+    mkdir hello
+    protoc -I . --python_betterproto_out=lib example.proto
+
+or run the following to invoke protoc via grpcio-tools:
+
+.. code-block:: sh
+
+    pip install grpcio-tools
+    python -m grpc_tools.protoc -I . --python_betterproto_out=lib example.proto
+
+
+This will generate ``lib/__init__.py`` which looks like:
+
+.. code-block:: python
+
+    # Generated by the protocol buffer compiler.  DO NOT EDIT!
+    # sources: example.proto
+    # plugin: python-betterproto
+    from dataclasses import dataclass
+
+    import betterproto
+
+
+    @dataclass
+    class Greeting(betterproto.Message):
+        """Greeting represents a message you can tell a user."""
+
+        message: str = betterproto.string_field(1)
+
+
+Then to use it:
+
+.. code-block:: python
+
+    >>> from lib import Greeting
+
+    >>> test = Greeting()
+    >>> test
+    Greeting(message='')
+
+    >>> test.message = "Hey!"
+    >>> test
+    Greeting(message="Hey!")
+
+    >>> bytes(test)
+    b'\n\x04Hey!'
+    >>> Greeting().parse(serialized)
+    Greeting(message="Hey!")
+
+
+Async gRPC Support
+++++++++++++++++++
+
+The generated code includes `grpclib <https://grpclib.readthedocs.io/en/latest>`_ based
+stub (client) classes for rpc services declared in the input proto files.
+It is enabled by default.
+
+
+Given a service definition similar to the one below:
+
+.. code-block:: proto
+
+    syntax = "proto3";
+
+    package echo;
+
+    message EchoRequest {
+      string value = 1;
+      // Number of extra times to echo
+      uint32 extra_times = 2;
+    }
+
+    message EchoResponse {
+      repeated string values = 1;
+    }
+
+    message EchoStreamResponse  {
+      string value = 1;
+    }
+
+    service Echo {
+      rpc Echo(EchoRequest) returns (EchoResponse);
+      rpc EchoStream(EchoRequest) returns (stream EchoStreamResponse);
+    }
+
+The generated client can be used like so:
+
+.. code-block:: python
+
+    import asyncio
+    from grpclib.client import Channel
+    import echo
+
+
+    async def main():
+        channel = Channel(host="127.0.0.1", port=50051)
+        service = echo.EchoStub(channel)
+        response = await service.echo(value="hello", extra_times=1)
+        print(response)
+
+        async for response in service.echo_stream(value="hello", extra_times=1):
+            print(response)
+
+        # don't forget to close the channel when you're done!
+        channel.close()
+
+    asyncio.run(main())  # python 3.7 only
+
+    # outputs
+    EchoResponse(values=['hello', 'hello'])
+    EchoStreamResponse(value='hello')
+    EchoStreamResponse(value='hello')
+
+
+JSON
+++++
+Message objects include :meth:`betterproto.Message.to_json` and
+:meth:`betterproto.Message.from_json` methods for JSON (de)serialisation, and
+:meth:`betterproto.Message.to_dict`, :meth:`betterproto.Message.from_dict` for
+converting back and forth from JSON serializable dicts.
+
+For compatibility the default is to convert field names to
+:attr:`betterproto.Casing.CAMEL`. You can control this behavior by passing a
+different casing value, e.g:
+
+.. code-block:: python
+
+    @dataclass
+    class MyMessage(betterproto.Message):
+        a_long_field_name: str = betterproto.string_field(1)
+
+
+    >>> test = MyMessage(a_long_field_name="Hello World!")
+    >>> test.to_dict(betterproto.Casing.SNAKE)
+    {"a_long_field_name": "Hello World!"}
+    >>> test.to_dict(betterproto.Casing.CAMEL)
+    {"aLongFieldName": "Hello World!"}
+
+    >>> test.to_json(indent=2)
+    '{\n  "aLongFieldName": "Hello World!"\n}'
+
+    >>> test.from_dict({"aLongFieldName": "Goodbye World!"})
+    >>> test.a_long_field_name
+    "Goodbye World!"