README.rst

   1 Introduction
   2 ============
   3
   4 .. image:: https://readthedocs.org/projects/adafruit-micropython-blinka/badge/?version=latest
   5     :target: https://circuitpython.readthedocs.io/projects/blinka/en/latest/
   6     :alt: Documentation Status
   7
   8 .. image:: https://img.shields.io/discord/327254708534116352.svg
   9     :target: https://adafru.it/discord
  10     :alt: Discord
  11
  12 .. image:: https://travis-ci.com/adafruit/Adafruit_Blinka.svg?branch=master
  13     :target: https://travis-ci.com/adafruit/Adafruit_Blinka
  14     :alt: Build Status
  15
  16 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
  17     :target: https://github.com/psf/black
  18     :alt: Code Style: Black
  19
  20 This repository contains a selection of packages emulating the CircuitPython API
  21 for devices or hosts running CPython or MicroPython. Working code exists to emulate these CircuitPython packages:
  22
  23 * **_typing** - (Legacy) subset of types for C-level protocols
  24 * **analogio** - analog input/output pins, using pin identities from board+microcontroller packages
  25 * **bitbangio** - software-driven interfaces for I2C, SPI
  26 * **board** - breakout-specific pin identities
  27 * **busio** - hardware-driven interfaces for I2C, SPI, UART
  28 * **circuitpython_typing** - Subset of types for C-level protocols
  29 * **digitalio** - digital input/output pins, using pin identities from board+microcontroller packages
  30 * **keypad** - support for scanning keys and key matrices
  31 * **microcontroller** - chip-specific pin identities
  32 * **micropython** - MicroPython-specific module
  33 * **neopixel_write** - low-level interface to NeoPixels
  34 * **pulseio** - contains classes that provide access to basic pulse IO (PWM)
  35 * **pwmio** - contains classes that provide access to basic pulse IO (PWM)
  36 * **rainbowio** - provides the colorwheel() function
  37
  38 For details, see the `Blinka API reference
  39 <https://circuitpython.readthedocs.io/projects/blinka/en/latest/index.html>`_.
  40
  41 Dependencies
  42 =============
  43
  44 The emulation described above is intended to provide a
  45 CircuitPython-like API for devices which are running CPython or
  46 Micropython. Since corresponding packages should be built-in to any
  47 standard CircuitPython image, they have no value on a device already
  48 running CircuitPython and would likely conflict in unhappy ways.
  49
  50 The test suites in the test/src folder under **testing.universal** are by design
  51 intended to run on *either* CircuitPython *or* CPython/Micropython+compatibility layer to prove conformance.
  52
  53 Installing from PyPI
  54 =====================
  55
  56 On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
  57 PyPI <https://pypi.org/project/Adafruit-Blinka/>`_. To install for current user:
  58
  59 .. code-block:: shell
  60
  61     pip3 install Adafruit-Blinka
  62
  63 To install system-wide (this may be required in some cases):
  64
  65 .. code-block:: shell
  66
  67     sudo pip3 install Adafruit-Blinka
  68
  69 To install in a virtual environment in your current project:
  70
  71 .. code-block:: shell
  72
  73     mkdir project-name && cd project-name
  74     python3 -m venv .env
  75     source .env/bin/activate
  76     pip3 install Adafruit-Blinka
  77
  78 Usage Example
  79 =============
  80
  81 At the time of writing (`git:7fc1f8ab <https://github.com/cefn/Adafruit_Micropython_Blinka/tree/7fc1f8ab477124628a5afebbf6826005955805f9>`_),
  82 the following sequence runs through some basic testing of the digitalio compatibility layer...
  83
  84 .. code-block:: python
  85
  86     from testing import test_module_name
  87     test_module_name("testing.universal.digitalio")
  88
  89 An example log from running the suites is `here <https://github.com/cefn/Adafruit_Micropython_Blinka/issues/2#issuecomment-366713394>`_ .
  90
  91 Contributing
  92 ============
  93
  94 Contributions are welcome! Please read our `Code of Conduct
  95 <https://github.com/adafruit/Adafruit_Blinka/blob/master/CODE_OF_CONDUCT.md>`_
  96 before contributing to help this project stay welcoming.
  97
  98 Building locally
  99 ================
 100
 101 Sphinx documentation
 102 -----------------------
 103
 104 Sphinx is used to build the documentation based on rST files and comments in the code. First,
 105 install dependencies (feel free to reuse the virtual environment from above):
 106
 107 .. code-block:: shell
 108
 109     python3 -m venv .env
 110     source .env/bin/activate
 111     pip install Sphinx sphinx-rtd-theme Adafruit-PlatformDetect
 112
 113 Now, once you have the virtual environment activated:
 114
 115 .. code-block:: shell
 116
 117     cd docs
 118     sphinx-build -E -W -b html . _build/html
 119
 120 This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
 121 view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
 122 locally verify it will pass.