search

sensorium / Mozzi

sound synthesis library for Arduino
https://sensorium.github.io/Mozzi/
GNU Lesser General Public License v2.1
1.09k stars 187 forks source link

HTML styling not rendering in the Github's Readme #257

Closed tomcombriat closed 5 months ago

tomcombriat commented 5 months ago

The website has been successfully updated, but the Readme on the github page does not render the styling of the tested boards table.

If I am correct, this readme is not linked to the website directly, so I guess we will have to resort to a pure markdown table for the github?

sensorium commented 5 months ago

I think you're correct, Tom. The readme isn't linked. It would be great if it could be. Maybe if it needed updating often either the readme or the web page could be generated from the other with a script as part of the general update process?

tfry-git commented 5 months ago

Ouch. That table was quite a pain to format (and I had tried to create it in pure markdown, before, but concluded that simply didn't work out).

Apparently, github filters out most tags, while rendering (supposedly, this is the script: https://github.com/gjtorikian/html-pipeline/blob/main/lib/html_pipeline/sanitization_filter.rb). Not sure, what could reasonably be done.

Also, yes, readme and webpage are not linked, and they had already diverged quite a bit. Automatically syncing the two sounds good, but won't help us with this particular issue. One approach might be to strip down the readme to perhaps the intro and license information, and replace everything else with links to the website.

tomcombriat commented 5 months ago

There is also the possibility to resort only to Markdown, that would ease the sync process (not that I do not like the colored table), for instance something like:

Table is not necessarily complete. Abbreviations explained below the table. The default output mode is in bold for each row. If stereo is supported, in a mode, the cell PWM-1 has two numbers with the second pin number is given in parentheses (+X).

Board or family / Output mode PWM-1 PWM-2 PDM inbuilt DAC I2S DAC (native)
ATmega328/168: Uno (R3), Nano, Pro Mini, Duemilanove, Leonardo, etc. 9 (+10) 9, 10
ATmega32U4: Teensy, Teensy2, 2++ B5/B6 correspond to pins 14/15 in Arduino B5 (+B6) B5, B6
ATmega2560: Arduino Mega, Freetronics EtherMega, etc. 11 (+12) 11, 12
ATmega1284: Sanguino 13 (+12) 13, 12
Teensy3.x - note: DAC Pin number depends on model: A14, A12, or A21 DAC
Teensy4.x A8 (+A9)
LGT8F328P: "Register clone" of the ATmega328, uses the same code in Mozzi 9 (+10) 9, 10
SAMD: Arduino Nano 33 Iot, Adafruit Playground Express, Gemma M0 etc. A0/Speaker
Renesas Arduino Core: Arduino Uno R4 A0
Arduino MBED Core: Arduino Giga (only model tested so far in this family) SERIAL2TX A13 (+A12)
STM32 maple core: Various STM32F1 and STM32F4 boards, "Blue/Black Pill" PB8 (+PB9) PB8, PB9
STM32duino (STM official) core: Huge range of STM32Fx boards PA8 (+PA9) PA8, PA9
ESP8266: ESP-01, Wemos D1 mini, etc. note: Beware of erratic pin labels GPIO2 yes
ESP32: note: Beware of vastly different pin labels across board variants yes GPIO25 (+GPIO26) yes
RP2040: Raspberry Pi Pico and friends 0 (+1) 0, 1 yes
tfry-git commented 5 months ago

Well, for a quick fix, I've copied your markdown table to the README, while leaving the webpage as is, for now.

tomcombriat commented 5 months ago

Top, I'll throw the release shortly. Except for the ease of reading, this table conveys the same information than the HTML one right? Or did I miss something?

tomcombriat commented 5 months ago

(Just saw that the "Using Mozzi" section also has a few problems :/ )

tfry-git commented 5 months ago

Top, I'll throw the release shortly. Except for the ease of reading, this table conveys the same information than the HTML one right? Or did I miss something?

Looks complete to me.

tomcombriat commented 5 months ago

Ok, that's a bit less visually appealing but that can always be a fallback if we want to have a "common table" somewhere in the future.