adafruit / adafruit/circuitpython-org

Outdated guide "how-to-add-a-new-board-to-the-circuitpython-org-website"

Open
#1,409 3 comments 0 reactions 1 assignee Claimed by @makermelissa View on GitHub
Dominant language
HTML
Stars
170
Forks
754
Avg merge
1d 3h
Merged PRs (30d)
6

Description

I'm struggling with my PR https://github.com/adafruit/circuitpython-org/pull/1408

This guide is outdated: https://learn.adafruit.com/how-to-add-a-new-board-to-the-circuitpython-org-website/adding-to-downloads

1. It needs to explain how to properly fork the website, **including the automatic checking stuff**. ( This doesn't work ```pre-commit install``` Because ```.pre-commit-config.yaml``` is missing... )

2. It needs to update the features - some I can think of include:-

* MicroSD card reader
* USB Serial
* PSRAM
* Buttons
* Joystick
* Touch input
* Ambient light sensor
* IMU
* Compass
* Magnetometer

It probably doesn't make sense to limit the features and block boards from adding new ones they support - this makes it frustrating for developers and users alike, when new things they're trying to do don't have the correct supporting documentation.

3. Someone needs to sanitize the existing board features... there's 17 in-use in the existing boards, but only 15 allowed in the documentation, and some of them are confusingly ambiguous (what does "USB-C" mean? Why are the other USB ports missing? How does the *actual* feature of the USB get "featured", like HID? Storage? Serial? UVC, Networking, security, printing, audio..). What's "Robotics" and "Solder-Free Alligator Clip" supposed to mean, and why do those exist when more usual things (like SD cards etc) don't?

Here's the list of existing features in all boards:
```cat _boards/* | perl -ne 'print if($f && /^ \- /) ; $f=0 unless(/^\s/); $f=1 if(/^features:/); ' | sort | uniq ```

- Arduino Shield Compatible
- Battery Charging
- Bluetooth/BTLE
- Breadboard-Friendly
- Camera
- Display
- External Display
- Feather-Compatible
- GPS
- LoRa/Radio
- Robotics
- Solder-Free Alligator Clip
- Speaker
- STEMMA QT/QWIIC
- USB-C
- Wi-Fi
- Xiao / QTPy Form Factor

4. The upload check itself is broken - instead of reporting what it's not happy about, it blows up with missing key errors

```
Run python3 tools/check-boards.py
Traceback (most recent call last):
File "/home/runner/work/circuitpython-org/circuitpython-org/tools/check-boards.py", line 122, in
if not verify_features("_board", acceptable_features):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/runner/work/circuitpython-org/circuitpython-org/tools/check-boards.py", line 40, in verify_features
metadata, _ = frontmatter.parse(f.read())
^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/frontmatter/__init__.py", line 92, in parse
fm_data = handler.load(fm)
^^^^^^^^^^^^^^^^
File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/frontmatter/default_handlers.py", line 260, in load
return yaml.load(fm, **kwargs) # type: ignore[arg-type]
^^^^^^^^^^^^^^^^^^^^^^^
File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/yaml/__init__.py", line 81, in load
return loader.get_single_data()
^^^^^^^^^^^^^^^^^^^^^^^^
File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/yaml/constructor.py", line 49, in get_single_data
node = self.get_single_node()
^^^^^^^^^^^^^^^^^^^^^^
File "yaml/_yaml.pyx", line 673, in yaml._yaml.CParser.get_single_node
File "yaml/_yaml.pyx", line 687, in yaml._yaml.CParser._compose_document
File "yaml/_yaml.pyx", line 731, in yaml._yaml.CParser._compose_node
File "yaml/_yaml.pyx", line 847, in yaml._yaml.CParser._compose_mapping_node
File "yaml/_yaml.pyx", line 860, in yaml._yaml.CParser._parse_next_event
yaml.parser.ParserError: while parsing a block mapping
in "", line 2, column 1
did not find expected key
in "", line 6, column 16
Error: Process completed with exit code 1.

```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.