Annual rewrite (#7)

Changelog:
    - change from setup.py to pyproject.toml
    - add Handler objects to make receiving headers easier
    - allow headers to take positional arguments
    - remove type checking
    - rename YDLClient to Client and run_ydl_server to server
    - update tutorial a bit
    - add sphinx documentation

.github/workflows/documentation.yaml

@@ -0,0 +1,18 @@
+name: Deploy Sphinx documentation to Pages
+
+on:
+  push:
+    branches: [main] # branch to trigger deployment
+
+jobs:
+  pages:
+    runs-on: ubuntu-20.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - id: deployment
+      uses: sphinx-notes/pages@v3

.gitignore

@@ -0,0 +1 @@
+**/__pycache__

README.md

@@ -10,7 +10,3 @@ You can install YDL from PyPI:
 ```
 python -m pip install ydl-ipc
 ```
-
-## Documentation
-
-Check out the tutorial in the docs folder!

docs/.gitignore

@@ -0,0 +1 @@
+_build/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,14 @@
+# Docs
+
+## Quickstart
+
+To run build/run the docs locally, do the following in this `docs` folder:
+
+ - Install docs dependencies: `pip install -r requirements.txt`
+ - run `make html` to generate html files
+ - in `_build/html` folder, run `python3 -m http.server`
+
+
+## How does this work?
+
+The documentation is built using Sphinx, using the Read The Docs theme, and using the Sphinx autodoc extension for the API page. It's deployed to github pages via a [github action](../.github/workflows/documentation.yaml).

docs/conf.py

@@ -0,0 +1,36 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import sys
+import os
+sys.path.append(os.path.abspath('..')) # add source for autodocs
+
+project = 'YDL'
+copyright = '2022, Pioneers in Engineering'
+author = 'Pioneers in Engineering'
+release = '0.2.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+
+
+extensions = [
+    "sphinx.ext.autodoc"
+]
+
+templates_path = []
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = []

docs/index.rst

@@ -0,0 +1,24 @@
+.. ydl documentation master file, created by
+   sphinx-quickstart on Wed Jun 28 20:01:50 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+YDL
+===============================
+
+YDL is a simple inter-process communication framework. It is cross-platform and built on TCP sockets.
+
+The name stands for Yheavyweight Dcommunications and Lmarshalling, with the acronym being pronounced "yodel".
+
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   installation.rst
+   tutorial.rst
+   reference.rst
+   technicals.rst
+
+

docs/installation.rst

@@ -0,0 +1,9 @@
+Installation
+=============
+
+
+Install YDL with pip:
+
+.. code-block:: bash
+
+    python3 -m pip install --upgrade ydl-ipc

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/reference.rst

@@ -0,0 +1,26 @@
+.. py:module:: ydl
+.. py:currentmodule:: ydl
+
+API Reference
+=================
+
+.. py:attribute:: DEFAULT_HOST
+    :type: str
+
+    The default host that the server and client bind to.
+
+.. py:attribute:: DEFAULT_PORT
+    :type: int
+
+    The default port that the server and client bind to.
+
+.. autoclass:: Client
+   :members:
+
+.. autoclass:: Handler
+   :members:
+
+.. autofunction:: header
+
+.. autofunction:: run_server
+

docs/requirements.txt

@@ -0,0 +1,3 @@
+# requirements for building docs
+sphinx
+sphinx_rtd_theme

docs/technicals.rst

@@ -0,0 +1,11 @@
+Random Notes
+=========================
+
+
+Note that YDL operates on a many-to-many messaging model, so you can have several processes listen on the same channel if needed. This might be useful for logging; you can have a logging process listen to all your channels, without changing the behavior of your application at all.
+
+A client may listen to any number of channels, as long as they're all passed as arguments to the constructor.
+
+Clients will connect to the server in the ``Client()`` constructor; note that this will block if the server isn't available. Both ``send()`` and ``receive()`` will block and try to reconnect if the connection is lost.
+
+If the server goes down, it may simply be restarted without too much chaos. Some messages may be lost if they were sent just before the server went down or just after it comes back up. This is somewhat unavoidable, so if you need to guarantee that a message was sent, you should implement confirmation messages. Actually, if you need that kind of guarantee, you should just use an industrial-strength solution like RabbitMQ or Apache Kafka.