adjust README; add CONTRIBUTING guide

and some additional tweaks to the docs...

Author: 2bndy5

CONTRIBUTING.rst

@@ -0,0 +1,78 @@
+
+Contributing Guidelines
+=======================
+
+Building the Documentation
+--------------------------
+
+To build library documentation, you need to install Graphviz and the documentation dependencies.
+
+.. code-block:: shell
+
+    pip install -r docs/requirements.txt
+
+.. note::
+    Installing graphviz differs depending on your platform.
+
+    Linux users can simply,
+
+    .. code-block:: shell
+
+        sudo apt-get install graphviz
+
+    Windows users will have to install the binaries from
+    `the official Graphviz downloads <https://graphviz.org/download/#windows>`_. Just be sure that
+    the installed ``bin`` folder is added to your environment's PATH variable.
+
+Finally, build the documentation with Sphinx:
+
+.. code-block:: shell
+
+    sphinx-build -E -W docs docs/_build/html
+
+The rendered HTML files should now be located in the ``docs/_build/html`` folder. Point your
+internet browser to this path and check the changes have been rendered properly.
+
+Linting the source code
+-----------------------
+
+.. _pre-commit: https://pre-commit.com/
+
+This library uses pre-commit_ for some linting tools like
+
+- `black <https://black.readthedocs.io/en/stable/>`_
+- `pylint <https://pylint.pycqa.org/en/stable/>`_
+- `mypy <https://mypy.readthedocs.io/en/stable/>`_
+
+To use pre-commit_, you must install it and create the cached environments that it needs.
+
+.. code-block:: shell
+
+    pip install pre-commit
+    pre-commit install
+
+Now, every time you commit something it will run pre-commit_ on the changed files. You can also
+run pre-commit_ on staged files:
+
+.. code-block:: shell
+
+    pre-commit run
+
+Testing the source code
+-----------------------
+
+.. _pytest: https://docs.pytest.org/en/latest/
+.. _coverage: https://coverage.readthedocs.io/en/latest/
+
+Code coverage/testing is done with pytest_ and coverage_ libraries. Install these tools (and
+this library's dependencies) with:
+
+.. code-block:: shell
+
+    pip install -r test/requirements.txt -r requirements.txt
+
+Run the tests and collect the code coverage with:
+
+.. code-block:: shell
+
+    coverage run -m pytest

README.rst

@@ -3,7 +3,7 @@ Introduction
 
 
 .. image:: https://readthedocs.org/projects/circuitpython-homie/badge/?version=latest
-    :target: https://circuitpython-homie.readthedocs.io/
+    :target: https://circuitpython-homie.rtfd.io/
     :alt: Documentation Status
 .. image:: https://github.com/2bndy5/CircuitPython_Homie/workflows/Build%20CI/badge.svg
     :target: https://github.com/2bndy5/CircuitPython_Homie/actions
@@ -20,27 +20,24 @@ Homie specifications for MQTT implemented in CircuitPython
     :width: 50%
 
 Dependencies
-=============
+------------
+
 This driver depends on:
 
 * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+* `Adafruit MiniMQTT Library <https://docs.circuitpython.org/projects/minimqtt/en/latest/>`_
 
 Please ensure all dependencies are available on the CircuitPython filesystem.
 This is easily achieved by downloading
 `the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_
-or individual libraries can be installed using
-`circup <https://github.com/adafruit/circup>`_.
+or individual libraries can be installed using `circup <https://github.com/adafruit/circup>`_.
 
 Installing from PyPI
-=====================
-
-.. note::
-    This library is not available on PyPI yet. Install documentation is included
-    as a standard element. Stay tuned for PyPI availability!
+--------------------
 
-.. admonition:: todo
+.. code-block:: shell
 
-    Remove the above note if PyPI version is/will be available at time of release.
+    pip install circuitpython-homie
 
 On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 PyPI <https://pypi.org/project/circuitpython-homie/>`_.
@@ -61,12 +58,12 @@ To install in a virtual environment in your current project:
 .. code-block:: shell
 
     mkdir project-name && cd project-name
-    python3 -m venv .venv
+    python3 -m venv .env
     source .env/bin/activate
     pip3 install circuitpython-homie
 
 Installing to a Connected CircuitPython Device with Circup
-==========================================================
+**********************************************************
 
 Make sure that you have ``circup`` installed in your Python environment.
 Install it with the following command if necessary:
@@ -88,24 +85,32 @@ Or the following command to update an existing version:
 
     circup update
 
-Usage Example
-=============
+Usage Examples
+--------------
 
-.. admonition:: todo
+Using the examples requires a secrets.py file that stores your secret information about the MQTT
+broker and network settings. This is `described with detail in the documentation
+<https://circuitpython-homie.rtfd.io/en/latest/examples.html>`_.
 
-    Add a quick, simple example. It and other examples should live in the
-    examples folder and be included in docs/examples.rst.
+See the examples in the
+`examples <https://github.com/2bndy5/CircuitPython_Homie/tree/main/examples>`_ folder.
+These will be included with the Circuitpython Community bundle as well.
 
 Documentation
-=============
-API documentation for this library can be found on `Read the Docs <https://circuitpython-homie.readthedocs.io/>`_.
+-------------
+
+.. _Contributing Guidelines: https://circuitpython-homie.rtfd.io/en/latest/contributing.html
 
-For information on building library documentation, please check out
-`this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.
+API documentation for this library can be found on
+`Read the Docs <https://circuitpython-homie.rtfd.io/>`_.
+
+Instructions for build the documentation is in our `Contributing Guidelines`_.
 
 Contributing
-============
+------------
 
 Contributions are welcome! Please read our `Code of Conduct
 <https://github.com/2bndy5/CircuitPython_Homie/blob/HEAD/CODE_OF_CONDUCT.md>`_
 before contributing to help this project stay welcoming.
+
+See also our `Contributing Guidelines`_ for information about the development workflow.

circuitpython_homie/__init__.py

@@ -2,8 +2,11 @@
 #
 # SPDX-License-Identifier: MIT
 """
-This module holds the Homie implementation for a device.
-See the nodes.py and properties.py for other Homie implementations.
+The :mod:`circuitpython_homie` module holds the Homie implementations for a
+:class:`device <HomieDevice>`, :class:`node <HomieNode>`, and
+:class:`property <HomieProperty>`. See the :mod:`circuitpython_homie.recipes` module
+for specialized properties that implement certain datatypes defined by the
+`Homie Specifications <https://homieiot.github.io/specification#payload>`_.
 """
 try:
     from os import uname  # type: ignore
@@ -118,7 +121,7 @@ def __init__(
         datatype = datatype.lower()
         if datatype not in PAYLOAD_TYPES:
             raise ValueError("{} datatype is not in {}".format(datatype, PAYLOAD_TYPES))
-        #: The property's :homie-attr:`datatype` attribute
+        #: The property's :homie-attr:`datatype` attribute.
         self.datatype = datatype
         #: The property's value.
         self._value = init_value
@@ -207,16 +210,31 @@ def callback(self):
         Conventionally, this will require echoing the data back to the broker as
         confirmation.
 
+        .. seealso::
+            Use `HomieDevice.set_property()` to echo back a confirmation to the MQTT
+            broker.
         .. code-block:: python
 
-            my_prop = HomieProperty("signage", settable=True)
+            prop1 = HomieProperty("signage", settable=True)
 
             def new_signage(client: MQTT, topic, :str, message: str):
-                print("received:", message)
-                my_homie_device.set_property(my_prop, message)
-                print("confirmation sent to broker")
+                # let `my_device` be the instantiated HomieDevice object
+                my_device.set_property(prop1, message)  # confirm with broker
+                # Optionally do something with the new value
+                print("received:", prop1.value)
 
-            my_prop.callback = new_signage
+            prop1.callback = new_signage
+        .. details:: Using a lambda
+            :class: info
+
+            CircuitPython also supports `lambda` objects.
+
+            .. code-block:: python
+
+                prop2 = HomieProperty("signage", settable=True)
+                prop2.callback = lambda *args: my_device.set_property(prop2, args[2])
+
+            This assumes that the property's `value` will be used elsewhere.
         """
         if not self.is_settable():
             return None

circuitpython_homie/recipes.py

@@ -1,5 +1,5 @@
-"""The ``recipes`` module holds any suggested recipes for easily implementing common
-node properties.
+"""The :mod:`circuitpython_homie.recipes` module holds any suggested recipes for easily
+implementing common node properties.
 
 .. important::
     Callback methods are not templated for these properties. Users are advised to

docs/API/topology.rst

@@ -1,6 +1,8 @@
 Topology
 ========
 
+.. automodule:: circuitpython_homie
+
 This library's data structures follows the
 `Homie specification's topology <https://homieiot.github.io/specification/#topology>`_.
 Because this implementation is written in pure python, the attributes of a Homie

docs/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst

docs/examples.rst

@@ -1,6 +1,9 @@
 Examples
 ========
 
+Prerequisites
+-------------
+
 All of these examples require a separate user-defined module named ``secrets.py``.
 In this secrets module should be 2 `dict`\ s:
 
@@ -25,6 +28,15 @@ In this secrets module should be 2 `dict`\ s:
         port=1883,  # the broker's port
     )
 
+Dependencies
+************
+
+Some examples use other third-party libraries (which are available in Adafruit's CircuitPython
+Library bundle). These libraries are listed in the examples/requirements.txt file for easy install.
+
+.. literalinclude:: ../examples/requirements.txt
+    :caption: examples/requirements.txt
+
 Simple test
 ------------
 

docs/index.rst

@@ -25,6 +25,11 @@
 
     tutorials/openhab
 
+.. toctree::
+    :hidden:
+
+    contributing
+
 .. include:: ../README.rst
 
 Indices and tables