Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/adafruit/cookiecutter-adafruit-circuitpython

Cookiecutter template for Adafruit's CircuitPython libraries.
https://github.com/adafruit/cookiecutter-adafruit-circuitpython

circuitpython

Last synced: about 9 hours ago
JSON representation

Cookiecutter template for Adafruit's CircuitPython libraries.

Awesome Lists containing this project

README 

        
Introduction

============



.. image :: https://img.shields.io/discord/327254708534116352.svg

    :target: https://adafru.it/discord

    :alt: Discord



This cookiecutter creates a project structure for an Adafruit CircuitPython library.



See this Adafruit Learn Guide for an explanation of creating a CircuitPython library: `Creating and sharing a CircuitPython library `_ The section for using cookiecutter is `here `_.



.. note::



    The above Learn Guide is directed towards creating a library for the Community Bundle. For libraries meant for the Adafruit Bundle, contact the CircuitPython Helpers (@circuitpython helpers) on Discord or put in a new issue on the Adafruit_CircuitPython_Bundle GitHub repository.



Cookiecutter Usage

===================



.. code-block:: bash



  # The first time

  pip install cookiecutter~=2.1



  cookiecutter gh:adafruit/cookiecutter-adafruit-circuitpython



Then, fill in the prompts and accomplish some post generation cleanup:



Prompts

--------



* ``target_bundle`` - Adafruit bundle or Community library bundle

* ``github_user`` - GitHub user or organization which will host this repo. For example, Adafruit funded libraries should say "adafruit" here.

* ``author_name`` - Who you are! Sets the copyright to you.

* ``company`` - Used to give Copyright credit to the company funding the library. For example, Adafruit funded libraries should say "Adafruit Industries" here.

* ``library_name`` - Shortest name for the library. Usually a chip name such as LIS3DH.

* ``library_description`` - Write a sentence describing the purpose of this library (e.g. ``CircuitPython helper library for the DC & Stepper Motor FeatherWing, Shield and Pi Hat kits.``).

* ``library_keywords`` - Used to populate keywords for PyPi. Enter a string of keywords (e.g ``dht temp humidity``) NOTE: The following are included by default: ``adafruit``, ``blinka``, ``circuitpython``, ``micropython``, and the ``library_name`` you enter.

* ``library_prefix`` - Used to prefix the code to the organization creating the library. For example, Adafruit supported libraries should say "adafruit" here. Do not add a - or _.

* ``adafruit_product_id`` -  The product ID for the Adafruit product includes a link to the product in the README. Only applies to Adafruit Bundle.

* ``requires_bus_device`` - Determines whether to add comments about a dependency on `BusDevice `_.

  If the library uses BusDevice, enter ``y`` or ``yes`` to include. If the library doesn't use BusDevice, all other entries including empty, will not include BusDevice.

* ``requires_register`` - Determines whether to add comments about a dependency on `Register `_.

  If the library uses Register, enter ``y`` or ``yes`` to include. If the library doesn't use Register, all other entries including empty, will not include Register.

* ``other_requirements`` - Adds any other module dependencies for PyPi. Enter a comma separated string of modules

  (e.g. ``adafruit-circuitpython-pca9685, adafruit-circuitpython-motor``). NOTE: ``Adafruit-Blinka`` is always included, so no need to include it here.

* ``sphinx_docs`` - Should the Sphinx based documentation be included in your repo? If so, enter ``y`` or ``yes`` to include the setup.py. For Adafruit libraries this defaults to Yes.



Post Generation Cleanup

------------------------



After generation, make sure to glance over the files to make sure they

autogenerated as you expect (such as capitalization). There are a few places

with ``.. todo::`` that should also be taken care of. After adding or updating

the information requested, make sure the ``.. todo::`` text is removed. Like this:



.. code::



    # Before Cleanup

    .. todo:: Describe what the module does



.. code::



    # After Cleanup

    This library talks to the AM4Z-1NG sensor. Typical use is for robot friends.



.. note::



    If you are not uploading the repository for Adafruit (i.e., the Community bundle), and you

    wish to use the Release feature on GitHub to upload libraries to PyPI, you will need to

    add your PyPI token to the repository secrets.  Set a secret named ``PYPI_USERNAME`` to

    ``__token__`` and a secret named ``PYPI_PASSWORD`` to your API token with the proper scope.

    Never share your API token anyone!



Windows Users

==============



Due to the development nature of cookiecutter, there are some limitations when using with Windows.



Cookiecutter Installation

--------------------------



The Python enviornment can be tricky sometimes in Windows. Use this documentation page for steps and tips on Windows installation: `Cookiecutter Installation - Windows `_



.py & /examples/_simpletest.py File Generation

------------------------------------------------------------------



Cookiecutter was developed for use in \*\nix/OSX enviornments. When implementing prompt based configuration for things like filenames, special characters were used for programmatic detection and formatting.



.. code-block::



    {% if cookiecutter.library_prefix %}{{ cookiecutter.library_prefix | lower }}_{% endif %}{{ cookiecutter.library_name | lower }}.py



As such, Windows will block the use of these special characters in filenames. So when cookiecutter pulls the Adafruit CircuitPython template, the .py and /examples/_simpletest.py files are not created. This adds an extra step. Simply copy an existing library's .py files (and structure if  making a "package"), and change the prompted values (e.g. author name, library name, documentation information, etc).



.. note::

    The above is from experience with using cookiecutter within a Windows native setup. This may not be applicable when using Windows Subsystem for Linux (WSL) or any *nix-For-Windows utilities.



    We are always exploring ways to make things easier, so this workflow may change. Also, ideas and solutions are always welcome!