Merge pull request #12 from sommersoft/new_docs

Improve Ref Docs

readthedocs.yml → .readthedocs.yml

@@ -1,4 +1,3 @@
 python:
     version: 3
-    pip_install: true
 requirements_file: requirements.txt

.travis.yml

@@ -16,15 +16,17 @@ deploy:
   provider: releases
   api_key: $GITHUB_TOKEN
   file_glob: true
-  file: bundles/*
+  file: $TRAVIS_BUILD_DIR/bundles/*
   skip_cleanup: true
+  overwrite: true
   on:
     tags: true
 
 install:
-  - pip install pylint circuitpython-build-tools
+  - pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme
 
 script:
   - pylint adafruit_register/*.py
   - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py)
   - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-register --library_location .
+  - cd docs && sphinx-build -E -W -b html . _build/html

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at support@adafruit.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

README.rst

@@ -1,5 +1,6 @@
-Adafruit CircuitPython Register library
-=======================================
+
+Introduction
+============
 
 .. image:: https://readthedocs.org/projects/adafruit-circuitpython-register/badge/?version=latest
     :target: https://circuitpython.readthedocs.io/projects/register/en/latest/
@@ -9,19 +10,28 @@ Adafruit CircuitPython Register library
     :target: https://discord.gg/nBQh6qu
     :alt: Discord
 
+.. image:: https://travis-ci.org/adafruit/Adafruit_CircuitPython_Register.svg?branch=master
+    :target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_Register
+    :alt: Build Status
+
 This library provides a variety of data descriptor class for `Adafruit
 CircuitPython <https://github.com/adafruit/circuitpython>`_ that makes it really
 simple to write a device drivers for a I2C and SPI register based devices. Data
 descriptors act like basic attributes from the outside which makes using them
 really easy to use.
 
-API
----
-.. toctree::
-    :maxdepth: 3
+Dependencies
+=============
+This driver depends on:
+
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 
-    adafruit_register/index
+Please ensure all dependencies are available on the CircuitPython filesystem.
+This is easily achieved by downloading
+`the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 
+Usage Example
+=============
 
 Creating a driver
 -----------------
@@ -158,9 +168,59 @@ Thats it! Now you can use your new register class like the example above. Just
 remember to keep the number of members to a minimum because the class may be
 used a bunch of times.
 
-Indices and tables
-------------------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/adafruit/Adafruit_CircuitPython_Register/blob/master/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.
+
+Building locally
+================
+
+To build this library locally you'll need to install the
+`circuitpython-build-tools <https://github.com/adafruit/circuitpython-build-tools>`_ package.
+
+.. code-block:: shell
+
+    python3 -m venv .env
+    source .env/bin/activate
+    pip install circuitpython-build-tools
+
+Once installed, make sure you are in the virtual environment:
+
+.. code-block:: shell
+
+    source .env/bin/activate
+
+Then run the build:
+
+.. code-block:: shell
+
+    circuitpython-build-bundles --filename_prefix adafruit-circuitpython-register --library_location .
+
+Sphinx documentation
+-----------------------
+
+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
+
+    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.
+
+

adafruit_register/i2c_bcd_alarm.py

@@ -21,8 +21,14 @@
 # THE SOFTWARE.
 # pylint: disable=too-few-public-methods
 
-"""`i2c_bcd_alarm` - Binary Coded Decimal alarm register
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"""
+"""
+`adafruit_register.i2c_bcd_alarm`
+====================================================
+
+Binary Coded Decimal alarm register
+
+* Author(s): Scott Shawcroft
+"""
 
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Register.git"
@@ -32,17 +38,15 @@
 def _bcd2bin(value):
     """Convert binary coded decimal to Binary
 
-    Arguments:
-    value - the BCD value to convert to binary (required, no default)
+    :param value: the BCD value to convert to binary (required, no default)
     """
     return value - 6 * (value >> 4)
 
 
 def _bin2bcd(value):
     """Convert a binary value to binary coded decimal.
 
-    Arguments:
-    value - the binary value to convert to BCD. (required, no default)
+    :param value: the binary value to convert to BCD. (required, no default)
     """
     return value + 6 * (value // 10)
 
@@ -65,10 +69,10 @@ class BCDAlarmTimeRegister:
 
     * "secondly", once a second (only if alarm has_seconds)
     * "minutely", once a minute when seconds match (if alarm doesn't seconds then when seconds = 0)
-    * "hourly", once an hour when `tm_min` and `tm_sec` match
-    * "daily", once a day when `tm_hour`, `tm_min` and `tm_sec` match
-    * "weekly", once a week when `tm_wday`, `tm_hour`, `tm_min`, `tm_sec` match
-    * "monthly", once a month when `tm_mday`, `tm_hour`, `tm_min`, `tm_sec` match
+    * "hourly", once an hour when ``tm_min`` and ``tm_sec`` match
+    * "daily", once a day when ``tm_hour``, ``tm_min`` and ``tm_sec`` match
+    * "weekly", once a week when ``tm_wday``, ``tm_hour``, ``tm_min``, ``tm_sec`` match
+    * "monthly", once a month when ``tm_mday``, ``tm_hour``, ``tm_min``, ``tm_sec`` match
 
     :param int register_address: The register address to start the read
     :param bool has_seconds: True if the alarm can happen minutely.

adafruit_register/i2c_bcd_datetime.py

@@ -20,9 +20,14 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 # pylint: disable=too-few-public-methods
+"""
+`adafruit_register.i2c_bcd_datetime`
+====================================================
 
-"""`i2c_bcd_datetime` - Binary Coded Decimal date and time register
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"""
+Binary Coded Decimal date and time register
+
+* Author(s): Scott Shawcroft
+"""
 
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Register.git"
@@ -32,17 +37,15 @@
 def _bcd2bin(value):
     """Convert binary coded decimal to Binary
 
-    Arguments:
-    value - the BCD value to convert to binary (required, no default)
+    :param value: the BCD value to convert to binary (required, no default)
     """
     return value - 6 * (value >> 4)
 
 
 def _bin2bcd(value):
     """Convert a binary value to binary coded decimal.
 
-    Arguments:
-    value - the binary value to convert to BCD. (required, no default)
+    :param value: the binary value to convert to BCD. (required, no default)
     """
     return value + 6 * (value // 10)
 

adafruit_register/i2c_bit.py

@@ -20,9 +20,14 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 # pylint: disable=too-few-public-methods
+"""
+`adafruit_register.i2c_bit`
+====================================================
 
-"""`i2c_bit` - Single bit registers
-++++++++++++++++++++++++++++++++"""
+Single bit registers
+
+* Author(s): Scott Shawcroft
+"""
 
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Register.git"

adafruit_register/i2c_bits.py

@@ -20,9 +20,14 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 # pylint: disable=too-few-public-methods
+"""
+`adafruit_register.i2c_bits`
+====================================================
 
-"""`i2c_bits` - Multi bit registers
-++++++++++++++++++++++++++++++++"""
+Multi bit registers
+
+* Author(s): Scott Shawcroft
+"""
 
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Register.git"

adafruit_register/i2c_struct.py

@@ -20,9 +20,13 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 # pylint: disable=too-few-public-methods
+"""
+`adafruit_register.i2c_struct`
+====================================================
+
+Generic structured registers based on `struct`
 
-"""`i2c_struct` - Generic structured registers based on `struct`
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+* Author(s): Scott Shawcroft
 """
 
 try:

adafruit_register/i2c_struct_array.py

@@ -20,9 +20,13 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 # pylint: disable=too-few-public-methods
+"""
+`adafruit_register.i2c_struct_array`
+====================================================
+
+Array of structured registers based on `struct`
 
-"""`i2c_struct_array` - Array of structured registers based on `struct`
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+* Author(s): Scott Shawcroft
 """
 
 try: