diff --git a/readthedocs.yml b/.readthedocs.yml similarity index 100% rename from readthedocs.yml rename to .readthedocs.yml diff --git a/.travis.yml b/.travis.yml index 024a8c3..234851c 100644 --- a/.travis.yml +++ b/.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_pca9685.py - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py) - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-pca9685 --library_location . + - cd docs && sphinx-build -E -W -b html . _build/html diff --git a/README.rst b/README.rst index 291b341..5be4c63 100644 --- a/README.rst +++ b/README.rst @@ -17,6 +17,8 @@ Dependencies This driver depends on: * `Adafruit CircuitPython `_ +* `Bus Device `_ +* `Register `_ Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading @@ -25,7 +27,7 @@ This is easily achieved by downloading Usage Example ============= -TODO +See examples/pca9685_simpletest.py for a demo of the usage. Contributing ============ @@ -34,10 +36,49 @@ Contributions are welcome! Please read our `Code of Conduct `_ before contributing to help this project stay welcoming. -API Reference -============= +Building locally +================ + +To build this library locally you'll need to install the +`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-pca9685 --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 -.. toctree:: - :maxdepth: 2 + cd docs + sphinx-build -E -W -b html . _build/html - api +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. \ No newline at end of file diff --git a/adafruit_pca9685.py b/adafruit_pca9685.py index d3dd685..2d40501 100755 --- a/adafruit_pca9685.py +++ b/adafruit_pca9685.py @@ -31,6 +31,21 @@ outputs for specific uses instead of generic duty_cycle adjustments. * Author(s): Scott Shawcroft + +Implementation Notes +-------------------- + +**Hardware:** + +* Adafruit `16-Channel 12-bit PWM/Servo Driver - I2C interface - PCA9685 + `_ (Product ID: 815) + +**Software and Dependencies:** + +* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards: + https://github.com/adafruit/circuitpython/releases +* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice +* Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register """ __version__ = "0.0.0-auto.0" @@ -89,16 +104,17 @@ def __getitem__(self, index): return self._channels[index] class PCA9685: - """Initialise the PCA9685 chip at ``address`` on ``i2c_bus``. + """ + Initialise the PCA9685 chip at ``address`` on ``i2c_bus``. - The internal reference clock is 25mhz but may vary slightly with environmental conditions and - manufacturing variances. Providing a more precise ``reference_clock_speed`` can improve the - accuracy of the frequency and duty_cycle computations. See the ``calibration.py`` example for - how to derive this value by measuring the resulting pulse widths. + The internal reference clock is 25mhz but may vary slightly with environmental conditions and + manufacturing variances. Providing a more precise ``reference_clock_speed`` can improve the + accuracy of the frequency and duty_cycle computations. See the ``calibration.py`` example for + how to derive this value by measuring the resulting pulse widths. - :param ~busio.I2C i2c_bus: The I2C bus which the PCA9685 is connected to. - :param int address: The I2C address of the PCA9685. - :param int reference_clock_speed: The frequency of the internal reference clock in Herz. + :param ~busio.I2C i2c_bus: The I2C bus which the PCA9685 is connected to. + :param int address: The I2C address of the PCA9685. + :param int reference_clock_speed: The frequency of the internal reference clock in Herz. """ # Registers: mode1_reg = UnaryStruct(0x00, ' + +.. toctree:: + :caption: Other Links + + Download + CircuitPython Reference Documentation + CircuitPython Support Forum + Discord Chat + Adafruit Learning System + Adafruit Blog + Adafruit Store + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/examples/simpletest.py b/examples/pca9685_simpletest.py similarity index 100% rename from examples/simpletest.py rename to examples/pca9685_simpletest.py