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://discord.gg/nBQh6qu
  10     :alt: Discord
  11
  12 .. image:: https://travis-ci.org/adafruit/Adafruit_Micropython_Blinka.svg?branch=master
  13     :target: https://travis-ci.org/adafruit/Adafruit__Micropython_Blinka
  14     :alt: Build Status
  15
  16 Description
  17 ===========
  18
  19 This repository contains a selection of packages mirroring the CircuitPython API
  20 on hosts running micropython. At the time of writing drafts exist for
  21
  22 * board - breakout-specific pin identities
  23 * microcontroller - chip-specific pin identities
  24 * digitalio - digital input/output pins, using pin identities from board/microcontroller
  25
  26
  27 Dependencies
  28 =============
  29
  30 The CircuitPython compatibility layers described above are intended for devices which
  31 are running Micropython. Given the top level packages should be provided by any standard
  32 CircuitPython image, you shouldn't be trying to put those packages on any board
  33 with CircuitPython already installed.
  34
  35 However, the test suites under testing.implementation.all are by design
  36 intended to run on either CircuitPython or the Micropython+compatibility layer, so that
  37 conformance can be achieved.
  38
  39 Similarly the test suites under testing.implementation.micropython should only be run
  40 on Micropython and testing.implementation.circuitpython should only be run on CircuitPython
  41
  42
  43 Usage Example
  44 =============
  45
  46 At the time of writing `git:3b2fc268 <https://github.com/cefn/Adafruit_Micropython_Blinka/tree/3b2fc268d89aee6a648da456224e6d48d2476baa>`,
  47 the following sequence runs through some basic testing of the digitalio compatibility layer.
  48
  49 .. code-block:: python
  50
  51     import testing
  52     testing.main()
  53
  54
  55 Contributing
  56 ============
  57
  58 Contributions are welcome! Please read our `Code of Conduct
  59 <https://github.com/adafruit/Adafruit_Micropython_Blinka/blob/master/CODE_OF_CONDUCT.md>`_
  60 before contributing to help this project stay welcoming.
  61
  62 Building locally
  63 ================
  64
  65 Sphinx documentation
  66 -----------------------
  67
  68 Sphinx is used to build the documentation based on rST files and comments in the code. First,
  69 install dependencies (feel free to reuse the virtual environment from above):
  70
  71 .. code-block:: shell
  72
  73     python3 -m venv .env
  74     source .env/bin/activate
  75     pip install Sphinx sphinx-rtd-theme
  76
  77 Now, once you have the virtual environment activated:
  78
  79 .. code-block:: shell
  80
  81     cd docs
  82     sphinx-build -E -W -b html . _build/html
  83
  84 This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
  85 view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
  86 locally verify it will pass.