Update documentation

Several documentation changes, including README and docstrings.
The only behaviour change is a meaningful error message in `__or__` (commit 41c000723ef66e80fd501ae1f922e2f59e0991f7)