Introduction
============

.. image :: https://img.shields.io/discord/327254708534116352.svg
    :target: https://discord.gg/nBQh6qu
    :alt: Discord

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

See this Adafruit Learn Guide for an explanation of creating a CircuitPython library: `Creating and sharing a CircuitPython library <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/overview>`_ The section for using cookiecutter is `here <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/creating-a-library#cookie-cutter>`_.

.. 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

  cookiecutter gh:adafruit/cookiecutter-adafruit-circuitpython

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

Prompts
--------

* ``library_name`` - Shortest name for the library. Usually a chip name such as LIS3DH.
* ``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 _.
* ``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.
* ``author`` - Who you are! Sets the copyright to you.
* ``github_user`` - GitHub user or organization which will host this repo. For example, Adafruit funded libraries should say "adafruit" here.
* ``company`` - Used to give Copyright credit to the company funding the library. For example, Adafruit funded libraries should say "Adafruit Industries" here.
* ``requires_bus_device`` - Determines whether to add comments about a dependency on `BusDevice <https://github.com/adafruit/Adafruit_CircuitPython_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 <https://github.com/adafruit/Adafruit_CircuitPython_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.

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.

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 <https://cookiecutter.readthedocs.io/en/latest/installation.html#windows>`_


<library>.py & /examples/<library>_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 <library>.py and /examples/<library>_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!