docs: Create the skeleton of documentation

secret_handshake/__init__.py

@@ -20,7 +20,13 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-"""Secret Handshake"""
+"""Secret Handshake
+================
+
+Something goes here.
+
+:class:`secret_handshake.network.SHSClient` and :class:`secret_handshake.network.SHSServer` are accessible from here.
+"""
 
 from .network import SHSClient, SHSServer
 

secret_handshake/boxstream.py

@@ -20,7 +20,9 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-"""Box stream utilities"""
+"""Box stream utilities
+--------------------
+"""
 
 from asyncio import IncompleteReadError, StreamReader, StreamWriter
 import struct
@@ -115,7 +117,24 @@ class UnboxStream:
 
 
 class BoxStream:
-    """Box stream"""
+    """This is the class that can write data into box streams
+
+    .. note::
+
+       Unless you plan to implement a new layer that can transmit box streams (e.g. Box stream over Bluetooth), you
+       won’t need this class.  Please check :class:`secret_handshake.network.SHSServer` and
+       :class:`secret_handshake.network.SHSClient`.
+
+    Example usage:
+
+    .. code-block:: python
+
+       # key is assumed to be the result of ``SigningKey.generate().encode()`` or similar.
+       #
+       # nonce is assumed to be the result of ``SHSClientCrypto(...).get_box_keys()`` or similar.
+       reader, writer = await asyncio.open_connection("host", 8008)
+       writer_stream = BoxStream(writer, key, nonce)
+    """
 
     def __init__(self, writer: StreamWriter, key: bytes, nonce: bytes):
         self.writer = writer
@@ -137,6 +156,8 @@ class BoxStream:
             self.writer.write(body[16:])
 
     def close(self) -> None:
-        """Close the box stream"""
+        """Close the box stream.
+
+        This will send 18 NUL-bytes"""
 
         self.writer.write(self.box.encrypt(b"\x00" * 18, self.nonce)[24:])

secret_handshake/crypto.py

@@ -20,7 +20,9 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-"""Cryptography functions"""
+"""Cryptography functions
+----------------------
+"""
 
 from base64 import b64decode
 import hashlib

secret_handshake/network.py

@@ -20,7 +20,9 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-"""Networking functionality"""
+"""Networking functionality
+------------------------
+"""
 
 from asyncio import StreamReader, StreamWriter, ensure_future, open_connection, start_server
 from typing import AsyncIterator, Awaitable, Callable, List, Optional

secret_handshake/util.py

@@ -20,7 +20,9 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-"""Utility functions"""
+"""Utilities
+---------
+"""
 
 import struct
 from typing import Generator, Sequence, TypeVar
@@ -56,7 +58,7 @@ def split_chunks(seq: Sequence[T], n: int) -> Generator[Sequence[T], None, None]
 
 # Stolen from PyCypto (Public Domain)
 def b(s: str) -> bytes:
-    """Shorthand for s.encode("latin-1")"""
+    """Shorthand for ``s.encode("latin-1")``"""
 
     return s.encode("latin-1")  # utf-8 would cause some side-effects we don't want