Skip to content

Commit bbfdf1a

Browse files
tekktriktekktrik
committed
Merge branch 'main' into evaherrada-patch-1
2 parents 164211f + d13b435 commit bbfdf1a

File tree

47 files changed

+297
-505
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+297
-505
lines changed

‎.github/workflows/test.yml

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,38 @@ on: [pull_request, push]
88

99
jobs:
1010
test:
11-
runs-on: ubuntu-latest
11+
strategy:
12+
matrix:
13+
python-version:
14+
- '3.7'
15+
- '3.x'
16+
17+
os-version:
18+
- ubuntu-latest
19+
- windows-latest
20+
- macos-latest
21+
22+
runs-on: ${{ matrix.os-version }}
1223
steps:
1324
- name: Dump GitHub context
1425
env:
1526
GITHUB_CONTEXT: ${{ toJson(github) }}
1627
run: echo "$GITHUB_CONTEXT"
17-
- name: Set up Python 3.x
28+
- name: Set up Python
1829
uses: actions/setup-python@v2
1930
with:
20-
python-version: "3.x"
31+
python-version: ${{ matrix.python-version }}
2132
- name: Versions
2233
run: |
2334
python3 --version
2435
- name: Checkout Current Repo
25-
uses: actions/checkout@v1
36+
uses: actions/checkout@v3
2637
with:
2738
submodules: true
2839
- name: Install deps
2940
run: |
3041
pip install --upgrade pip
31-
pip install -r $GITHUB_WORKSPACE/tests_requirements.txt
42+
pip install -r tests_requirements.txt
3243
- name: Run cookiecutter tests
3344
run: |
3445
pytest -v

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ _build
2121

2222
# Virtual environment-specific files
2323
.env
24+
.venv
2425

2526
# MacOS-specific files
2627
*.DS_Store

‎.pre-commit-config.yaml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,5 @@ repos:
1010
- repo: https://github.com/pre-commit/pre-commit-hooks
1111
rev: v4.2.0
1212
hooks:
13-
- id: check-yaml
1413
- id: end-of-file-fixer
1514
- id: trailing-whitespace

‎.reuse/dep5

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
2+
Upstream-Name: cookiecutter-adafruit-circuitpython
3+
Upstream-Contact: [email protected]
4+
Source: https://github.com/adafruit/cookiecutter-adafruit-circuitpython/
5+
6+
Files: {{ cookiecutter.__dirname }}/docs
7+
Copyright: 2017 Scott Shawcroft, written for Adafruit Industries
8+
License: MIT
9+
10+
Files: {{ cookiecutter.__dirname }}/docs/_static
11+
Copyright: 2018 Phillip Torrone for Adafruit Industries
12+
License: MIT

‎README.rst

Lines changed: 100 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,100 @@
1-
Introduction
2-
============
3-
4-
.. image :: https://img.shields.io/discord/327254708534116352.svg
5-
:target: https://adafru.it/discord
6-
:alt: Discord
7-
8-
This cookiecutter creates a project structure for a Adafruit CircuitPython
9-
library.
10-
11-
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>`_.
12-
13-
.. note::
14-
15-
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.
16-
17-
Cookiecutter Usage
18-
===================
19-
20-
.. code-block:: bash
21-
22-
# The first time
23-
pip install cookiecutter
24-
25-
cookiecutter gh:adafruit/cookiecutter-adafruit-circuitpython
26-
27-
Then, fill in the prompts and accomplish some post generation cleanup:
28-
29-
Prompts
30-
--------
31-
32-
* ``target_bundle`` - Adafruit bundle or Community library bundle
33-
* ``github_user`` - GitHub user or organization which will host this repo. For example, Adafruit funded libraries should say "adafruit" here.
34-
* ``author_name`` - Who you are! Sets the copyright to you.
35-
* ``company`` - Used to give Copyright credit to the company funding the library. For example, Adafruit funded libraries should say "Adafruit Industries" here.
36-
* ``library_name`` - Shortest name for the library. Usually a chip name such as LIS3DH.
37-
* ``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.``).
38-
* ``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.
39-
* ``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 _.
40-
* ``adafruit_product_id`` - The product ID for the Adafruit product includes a link to the product in the README. Only applies to Adafruit Bundle.
41-
* ``requires_bus_device`` - Determines whether to add comments about a dependency on `BusDevice <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_.
42-
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.
43-
* ``requires_register`` - Determines whether to add comments about a dependency on `Register <https://github.com/adafruit/Adafruit_CircuitPython_Register>`_.
44-
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.
45-
* ``other_requirements`` - Adds any other module dependencies for PyPi. Enter a comma separated string of modules
46-
(e.g. ``adafruit-circuitpython-pca9685, adafruit-circuitpython-motor``). NOTE: ``Adafruit-Blinka`` is always included, so no need to include it here.
47-
* ``pypi_release`` - Will this library be releaased on PyPI? If so, enter ``y`` or ``yes`` to include the setup.py. For Adafruit libraries this defaults to Yes.
48-
* ``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.
49-
50-
51-
Post Generation Cleanup
52-
------------------------
53-
54-
After generation, make sure to glance over the files to make sure they
55-
autogenerated as you expect (such as capitalization). There are a few places
56-
with ``.. todo::`` that should also be taken care of. After adding or updating
57-
the information requested, make sure the ``.. todo::`` text is removed. Like this:
58-
59-
.. code::
60-
61-
# Before Cleanup
62-
.. todo:: Describe what the module does
63-
64-
.. code::
65-
66-
# After Cleanup
67-
This library talks to the AM4Z-1NG sensor. Typical use is for robot friends.
68-
69-
Windows Users
70-
==============
71-
72-
Due to the development nature of cookiecutter, there are some limitations when using with Windows.
73-
74-
Cookiecutter Installation
75-
--------------------------
76-
77-
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>`_
78-
79-
80-
<library>.py & /examples/<library>_simpletest.py File Generation
81-
------------------------------------------------------------------
82-
83-
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.
84-
85-
.. code-block::
86-
87-
{% if cookiecutter.library_prefix %}{{ cookiecutter.library_prefix | lower }}_{% endif %}{{ cookiecutter.library_name | lower }}.py
88-
89-
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).
90-
91-
.. note::
92-
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.
93-
94-
We are always exploring ways to make things easier, so this workflow may change. Also, ideas and solutions are always welcome!
1+
Introduction
2+
============
3+
4+
.. image :: https://img.shields.io/discord/327254708534116352.svg
5+
:target: https://adafru.it/discord
6+
:alt: Discord
7+
8+
This cookiecutter creates a project structure for an Adafruit CircuitPython library.
9+
10+
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>`_.
11+
12+
.. note::
13+
14+
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.
15+
16+
Cookiecutter Usage
17+
===================
18+
19+
.. code-block:: bash
20+
21+
# The first time
22+
pip install cookiecutter~=2.1
23+
24+
cookiecutter gh:adafruit/cookiecutter-adafruit-circuitpython
25+
26+
Then, fill in the prompts and accomplish some post generation cleanup:
27+
28+
Prompts
29+
--------
30+
31+
* ``target_bundle`` - Adafruit bundle or Community library bundle
32+
* ``github_user`` - GitHub user or organization which will host this repo. For example, Adafruit funded libraries should say "adafruit" here.
33+
* ``author_name`` - Who you are! Sets the copyright to you.
34+
* ``company`` - Used to give Copyright credit to the company funding the library. For example, Adafruit funded libraries should say "Adafruit Industries" here.
35+
* ``library_name`` - Shortest name for the library. Usually a chip name such as LIS3DH.
36+
* ``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.``).
37+
* ``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.
38+
* ``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 _.
39+
* ``adafruit_product_id`` - The product ID for the Adafruit product includes a link to the product in the README. Only applies to Adafruit Bundle.
40+
* ``requires_bus_device`` - Determines whether to add comments about a dependency on `BusDevice <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_.
41+
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.
42+
* ``requires_register`` - Determines whether to add comments about a dependency on `Register <https://github.com/adafruit/Adafruit_CircuitPython_Register>`_.
43+
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.
44+
* ``other_requirements`` - Adds any other module dependencies for PyPi. Enter a comma separated string of modules
45+
(e.g. ``adafruit-circuitpython-pca9685, adafruit-circuitpython-motor``). NOTE: ``Adafruit-Blinka`` is always included, so no need to include it here.
46+
* ``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.
47+
48+
49+
Post Generation Cleanup
50+
------------------------
51+
52+
After generation, make sure to glance over the files to make sure they
53+
autogenerated as you expect (such as capitalization). There are a few places
54+
with ``.. todo::`` that should also be taken care of. After adding or updating
55+
the information requested, make sure the ``.. todo::`` text is removed. Like this:
56+
57+
.. code::
58+
59+
# Before Cleanup
60+
.. todo:: Describe what the module does
61+
62+
.. code::
63+
64+
# After Cleanup
65+
This library talks to the AM4Z-1NG sensor. Typical use is for robot friends.
66+
67+
.. note::
68+
69+
If you are not uploading the repository for Adafruit (i.e., the Community bundle), and you
70+
wish to use the Release feature on GitHub to upload libraries to PyPI, you will need to
71+
add your PyPI token to the repository secrets. Set a secret named ``PYPI_USERNAME`` to
72+
``__token__`` and a secret named ``PYPI_PASSWORD`` to your API token with the proper scope.
73+
Never share your API token anyone!
74+
75+
Windows Users
76+
==============
77+
78+
Due to the development nature of cookiecutter, there are some limitations when using with Windows.
79+
80+
Cookiecutter Installation
81+
--------------------------
82+
83+
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>`_
84+
85+
86+
<library>.py & /examples/<library>_simpletest.py File Generation
87+
------------------------------------------------------------------
88+
89+
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.
90+
91+
.. code-block::
92+
93+
{% if cookiecutter.library_prefix %}{{ cookiecutter.library_prefix | lower }}_{% endif %}{{ cookiecutter.library_name | lower }}.py
94+
95+
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).
96+
97+
.. note::
98+
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.
99+
100+
We are always exploring ways to make things easier, so this workflow may change. Also, ideas and solutions are always welcome!

‎cookiecutter.json

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22
"target_bundle": [
33
"Adafruit",
44
"Community",
5-
"CircuitPython Org"
5+
"CircuitPython Org",
6+
"test"
67
],
78
"github_user": "{%- if cookiecutter.target_bundle == 'Adafruit' -%} adafruit {%- elif cookiecutter.target_bundle == 'CircuitPython Org' -%} circuitpython {%- endif -%}",
89
"author_name": null,
@@ -15,8 +16,9 @@
1516
"requires_bus_device": "",
1617
"requires_register": "",
1718
"other_requirements": "",
18-
"pypi_release": "{%- if cookiecutter.target_bundle == 'Adafruit' or cookiecutter.target_bundle == 'CircuitPython Org' -%} yes {%- else -%} no {%- endif -%}",
1919
"sphinx_docs": "{%- if cookiecutter.target_bundle == 'Adafruit' or cookiecutter.target_bundle == 'CircuitPython Org' -%} yes {%- else -%} no {%- endif -%}",
2020
"_extensions": ["jinja2.ext.do"],
21-
"_copy_without_render": ["*.github/*"]
21+
"__dirname": "{% if cookiecutter.target_bundle != 'CircuitPython Org' %}{% if cookiecutter.library_prefix %}{{ cookiecutter.library_prefix | capitalize }}_CircuitPython{% else %}CircuitPython{% endif %}_{{ cookiecutter.library_name|replace(' ', '_')}}{% else %}CircuitPython_Org_{{ cookiecutter.library_name|replace(' ', '_')}}{% endif %}",
22+
"__libname": "{{ cookiecutter.library_name | lower | replace(' ', '_') }}",
23+
"__libprefix": "{% if cookiecutter.library_prefix %}{{ cookiecutter.library_prefix | lower | replace(' ', '_') }}_{% endif %}"
2224
}

‎hooks/post_gen_project.py

Lines changed: 0 additions & 32 deletions
This file was deleted.

‎hooks/pre_gen_project.py

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
1-
# SPDX-FileCopyrightText: 2021 Adafruit Industries
2-
#
3-
# SPDX-License-Identifier: MIT
4-
5-
"""
6-
Hooks that run before the template is rendered.
7-
"""
8-
9-
import sys
10-
11-
github_user = '{{cookiecutter.github_user}}'
12-
13-
if github_user in ["", None]:
14-
print("ERROR: github_user is a required field.")
15-
# exits with status 1 to indicate failure
16-
sys.exit(1)
1+
# SPDX-FileCopyrightText: 2022 Alec Delaney, written for Adafruit Industries
2+
#
3+
# SPDX-License-Identifier: MIT
4+
5+
import cookiecutter
6+
from pkg_resources import packaging
7+
8+
MIN_VERSION_SEMVER = "2.1"
9+
MIN_VERSION = packaging.version.parse(MIN_VERSION_SEMVER)
10+
11+
user_version_semver = cookiecutter.__version__
12+
user_version = packaging.version.parse(user_version_semver)
13+
14+
if MIN_VERSION > user_version:
15+
print("")
16+
print("!!! cookiecutter must be at a minimum of version", MIN_VERSION, "!!!")
17+
print("")
18+
raise SystemExit(1)

0 commit comments

Comments
 (0)