More documentation updates, specifically for developers who want to contribute.

README.rst

@@ -161,3 +161,92 @@ with development. Typing "make" on its own will list the options thus::
     make publish-test - publish the project to PyPI test instance.
     make publish-live - publish the project to PyPI production.
     make docs - run sphinx to create project documentation.
+
+How?
+####
+
+The ``circup`` tool checks for a connected CircuitPython device by
+interrogating the local filesystem to find a path to a directory which ends
+with ``"CIRCUITPYTHON"`` (the name under which a CircuitPython device is
+mounted by the host operating system). This is handled in the ``find_device``
+function.
+
+A Python module on a connected device is represented by an instance of the
+``Module`` class. This class provides useful methods for discerning if the
+module is out of date, returning useful representations of it in order to
+display information to the user, or updating the module on the connected
+device with whatever the version is in the latest Adafruit CircuitPython
+Bundle.
+
+All of the libraries included in the Adafruit CircuitPython Bundle contain,
+somewhere within their code, two metadata objects called ``__version__`` and
+``__repo__``.
+
+The ``__repo__`` object is a string containing the GitHub repository URL, as
+used to clone the project.
+
+The ``__version__`` object is interesting because *within the source code in
+Git* the value is **always** the string ``"0.0.0-auto.0"``. When a new release
+is made of the bundle, this value is automatically replaced by the build
+scripts to the correct version information, which will always conform to the
+`semver standard <https://semver.org/>`_.
+
+Given this context, the ``circup`` tool will check a configuration file
+to discern what *it* thinks is the latest version of the bundle. If there is
+no configuration file (for example, on first run), then the bundle version is
+assumed to be ``"0"``.
+
+Next, it checks GitHub for the tag value (denoting the version) of the very
+latest bundle release. Bundle versions are based upon the date of release, for
+instance ``"20190904"``. If the latest version on GitHub is later than the
+version ``circup`` currently has, then the latest version of the bundle
+is automatically downloaded and cached away somewhere.
+
+In this way, the ``circup`` tool is able to have available to it both a path
+to a connected CIRCUITPYTHON devce and a copy of the latest version, including
+the all important version information, of the Adafruit CircuitPython Bundle.
+
+Exactly the same function (``get_modules``) is used to extract the metadata
+from the modules on both the connected device and in the bundle cache. This
+metadata is used to instantiate instances of the ``Module`` class which is
+subsequently used to facilitate the various commands the tool makes available.
+
+These commands are defined at the very end of the ``circup.py`` code.
+
+Unit tests can be found in the ``tests`` directory. CircUp uses
+`pytest <http://www.pytest.org/en/latest/>`_ style testing conventions. Test
+functions should include a comment to describe its *intention*. We currently
+have 100% unit test coverage for all the core functionality (excluding
+functions used to define the CLI commands).
+
+To run the full test suite, type::
+
+    make check
+
+All code is formatted using the stylistic conventions enforced by
+`black <https://black.readthedocs.io/en/stable/>`_. The tidying of code
+formatting is part of the ``make check`` process, but you can also just use::
+
+    make tidy
+
+Please see the output from ``make`` for more information about the various
+available options to help you work with the code base. TL;DR ``make check``
+runs everything.
+
+Before submitting a PR, please remember to ``make check``. ;-)
+
+CircUp uses the `Click <https://click.palletsprojects.com/en/7.x/>`_ module to
+run command-line interaction. The
+`AppDirs <https://pypi.org/project/appdirs/>`_ module is used to determine
+where to store user-specific assets created by the tool in such a way that
+meets the host operating system's usual conventions. The
+`python-semver <https://github.com/k-bx/python-semver>`_ package is used to
+validate and compare the semver values associated with modules.
+
+Documentation, generated by `Sphinx <http://www.sphinx-doc.org/en/master/>`_,
+is based on this README and assembled by assets in the ``doc`` subdirectory.
+The latest version of the docs will be found on
+`Read the Docs <https://circup.readthedocs.io/>`_.
+
+Discussion of this tool happens on the Adafruit CircuitPython
+`Discord channel <https://discord.gg/rqrKDjU>`_.