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

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

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

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

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 <module>
    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 "<unicode string>", line 2, column 1
did not find expected key
  in "<unicode string>", line 6, column 16
Error: Process completed with exit code 1.

May 18 '24 06:05 gitcnd

It might be worth adding and enforcing a rule about what the .md file is supposed to be called (and documenting that).

The following boards exist, but do not have .md files for them:-

adafruit_feather_rp2040_rfm
crcibernetica-ideaboard
devkit_xg24_brd2601b
explorerkit_xg24_brd2703a
flipperzero_wifi_dev
heiafr_picomo_v2
renode_cortex_m0plus
sparkfun_thingplus_matter_mgm240p_brd2704a
wemos_lolin32_lite

The following .md files do not have any corresponding circuitpython/ports/*/board/ folders for them:-

adafruit_feather_esp32s2_bme280
adafruit_feather_rp2040_rfm69
adafruit_feather_rp2040_rfm9x
circuitplayground_express_4h
circuitplayground_express_digikey_pycon2019
crcibernetica_ideaboard
edgebadge
feather_radiofruit_zigbee
flipper-zero_wifi_devboard
gb_m4
gemma_m0_pycon2018
picomo_v2
pirkey_m0
pybadge_airlift
pygamer_advance
pyportal_pynt
silabs_devkit_xg24_brd2601b
silabs_explorerkit_xg24_brd2703a
sparkfun_thing_plus_matter_mgm240p
upico

Possibly a different system for board variants makes more sense, than duplicating an entire board .md file when nothing else (not even the firmware) is different?

May 18 '24 06:05 gitcnd

This section:-

board_id This should be the name of the board for example "feather_m4_express".

probably needs expanding to explain what "board_id" means, and the purpose of this - as best I can tell, this is the name of the folder that the board firmware definition files live in ? and I think it's probably used as a name inside some website build process the generates the firmware binaries, so this line tells the website which firmware goes with the board, right?

May 18 '24 07:05 gitcnd

Good ideas. Thanks for the suggestions. :) A lot of the enforcements were added after I had written the guide and you're right that it needs some updating.

May 21 '24 15:05 makermelissa