update docs

CONTRIBUTING.rst

@@ -0,0 +1,50 @@
+
+Contributing Guidelines
+=======================
+
+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
+
+.. note::
+    Use the ``--all-files`` argument to run pre-commit on all files in the repository.
+
+
+Building the Documentation
+--------------------------
+
+To build library documentation, you need to install the documentation dependencies.
+
+.. code-block:: shell
+
+    pip install -r docs/requirements.txt
+
+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.

docs/conf.py

@@ -111,7 +111,7 @@
             "primary": "green",
             "accent": "light-blue",
             "toggle": {
-                "icon": "material/toggle-switch-off-outline",
+                "icon": "material/lightbulb-outline",
                 "name": "Switch to dark mode",
             },
         },
@@ -121,14 +121,41 @@
             "primary": "green",
             "accent": "light-blue",
             "toggle": {
-                "icon": "material/toggle-switch",
+                "icon": "material/lightbulb",
                 "name": "Switch to light mode",
             },
         },
     ],
     # Set the repo location to get a badge with stats
     "repo_url": "https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle/",
     "repo_name": "CircuitPython_Cirque_Pinnacle",
+    "social": [
+        {
+            "icon": "fontawesome/brands/github",
+            "link": "https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle",
+        },
+        {
+            "icon": "fontawesome/brands/python",
+            "link": "https://pypi.org/project/circuitpython-cirque-pinnacle/",
+        },
+        {
+            "icon": "fontawesome/brands/discord",
+            "link": "https://adafru.it/discord",
+        },
+        {
+            "icon": "simple/adafruit",
+            "link": "https://www.adafruit.com/",
+        },
+        {
+            "icon": "simple/sparkfun",
+            "link": "https://www.sparkfun.com/",
+        },
+        {
+            "name": "CircuitPython Downloads",
+            "icon": "octicons/download-24",
+            "link": "https://circuitpython.org",
+        },
+    ],
 }
 
 sphinx_immaterial_custom_admonitions = [

docs/contributing.rst

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

docs/index.rst

@@ -19,22 +19,15 @@
     anymeas
 
 .. toctree::
-    :caption: Related Products
     :hidden:
 
-    Cirque Glidepoint circle trackpads <https://www.mouser.com/Search/Refine?Ntk=P_MarCom&Ntt=118816186>
-    12-pin FPC cable (0.5mm pitch) <https://www.mouser.com/Connectors/FFC-FPC/FFC-FPC-Jumper-Cables/_/N-axro3?P=1yc8ojpZ1z0wxjx>
+    contributing
 
 .. toctree::
-    :caption: Other Links
-    :hidden:
+    :caption: Related Products
 
-    Download <https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle/releases>
-    CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
-    CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
-    Adafruit Learning System <https://learn.adafruit.com>
-    Adafruit Blog <https://blog.adafruit.com>
-    Adafruit Store <https://www.adafruit.com>
+    Cirque Glidepoint circle trackpads <https://www.mouser.com/Search/Refine?Ntk=P_MarCom&Ntt=118816186>
+    12-pin FPC cable (0.5mm pitch) <https://www.mouser.com/Connectors/FFC-FPC/FFC-FPC-Jumper-Cables/_/N-axro3?P=1yc8ojpZ1z0wxjx>
 
 Introduction
 ============
@@ -97,14 +90,14 @@ bottom). The following table shows how the pins are connected in the `examples <
     1, SCK, SCK, "SPI clock line"
     2, SO, MISO, "Master Input Slave Output"
     3, SS, D7, "Slave Select (AKA Chip Select)"
-    4, DR, D2, """data ready"" interrupt"
+    4, DR, D2, "Data Ready interrupt"
     5, SI, MOSI, "SPI Master Output Slave Input"
     6, B2, N/A, "Hardware input button #2"
     7, B3, N/A, "Hardware input button #3"
     8, B1, N/A, "Hardware input button #1"
     9, SCL, SCL, "I2C clock line"
     10, SDA, SDA, "I2C data line"
-    11, GND, GND, "Ground"
+    11, GND, GND, Ground
     12, VDD, 3V, "3V power supply"
 
 .. tip:: Of course, you can capture button data manually (if your application utilizes more
@@ -149,15 +142,26 @@ This is easily achieved by downloading `the Adafruit library and driver bundle
 How to Install
 **************
 
+Using ``pip``
+~~~~~~~~~~~~~
+
 This library is deployed to pypi.org, so you can easily install this library
-using ``pip3 install circuitpython-cirque-pinnacle`` or use the following
-commands:
+using
+
+.. code-block:: shell
+
+    pip3 install circuitpython-cirque-pinnacle
+
+Using git source
+~~~~~~~~~~~~~~~~
+
+This library can also be installed from the git source repository.
 
 .. code-block:: shell
 
     git clone https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle.git
     cd CircuitPython_Cirque_Pinnacle
-    python3 setup.py install
+    python3 -m pip install .
 
 Usage Example
 *************
@@ -172,31 +176,13 @@ Contributions are welcome! Please read our `Code of Conduct
 <https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle/blob/master/CODE_OF_CONDUCT.md>`_
 before contributing to help this project stay welcoming.
 
-Sphinx documentation
-********************
+Please review our :doc:`contributing` for details on the development workflow and linting tools.
 
-Sphinx is used to build the documentation based on rST files and comments in the code. First,
-install dependencies (feel free to reuse the virtual environment from above):
-
-.. code-block:: shell
+To initiate a discussion of idea(s), you need only open an issue on the
+`source's git repository <https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle>`_
+(it doesn't have to be a bug report).
 
-    python3 -m venv .env
-    source .env/bin/activate
-    pip install Sphinx sphinx-rtd-theme
-
-Now, once you have the virtual environment activated:
-
-.. code-block:: shell
-
-    cd docs
-    sphinx-build -E -W -b html . _build/html
-
-This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
-view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
-locally verify it will pass.
-
-Indices and tables
-------------------
+Sphinx documentation
+********************
 
-* :ref:`genindex`
-* :ref:`modindex`
+Please read our :doc:`contributing` for instructions on how to build the documentation.