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