search

adafruit / circuitpython-org

CircuitPython's website
https://circuitpython.org
143 stars 509 forks source link

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

Open gitcnd opened 1 month ago

gitcnd commented 1 month ago

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

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.

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

  1. 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.
gitcnd commented 1 month ago

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

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

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?

gitcnd commented 1 month ago

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?

makermelissa commented 1 month ago

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.