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 import testing
  50 testing.main()
  51
  52
  53 Contributing
  54 ============
  55
  56 Contributions are welcome! Please read our `Code of Conduct
  57 <https://github.com/adafruit/Adafruit_Micropython_Blinka/blob/master/CODE_OF_CONDUCT.md>`_
  58 before contributing to help this project stay welcoming.
  59
  60 Building locally
  61 ================
  62
  63 Sphinx documentation
  64 -----------------------
  65
  66 Sphinx is used to build the documentation based on rST files and comments in the code. First,
  67 install dependencies (feel free to reuse the virtual environment from above):
  68
  69 .. code-block:: shell
  70
  71     python3 -m venv .env
  72     source .env/bin/activate
  73     pip install Sphinx sphinx-rtd-theme
  74
  75 Now, once you have the virtual environment activated:
  76
  77 .. code-block:: shell
  78
  79     cd docs
  80     sphinx-build -E -W -b html . _build/html
  81
  82 This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
  83 view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
  84 locally verify it will pass.