PIO / WS2812 / parallel -- documentation? about pico-examples HOT 5 CLOSED

Absolutely documentation very much welcome... this was just thrown together by me for my own testing and figured it might help someone ;-0

certainly some in source comments are useful and/or tidying up of code. Also maybe a README.adoc (@aallan can make suggestions about what he prefers)

from pico-examples.

Hey there! Yes, absolutely we'd love documentation PRs. If you take a look in the pico-examples repo you'll find that some of the directories have a README.adoc,

$ find . -name "README.adoc" -print
./i2c/lcd_1602_i2c/README.adoc
./i2c/mpu6050_i2c/README.adoc
./spi/bme280_spi/README.adoc
./spi/mpu9250_spi/README.adoc
./gpio/dht_sensor/README.adoc
./gpio/hello_7segment/README.adoc
$

These README.adoc files are the preferred method for documenting example code. If we take a look at the gpio/dht_sensor/ directory,

$ ls
total 1576
drwxr-xr-x  8 aa  staff   256B 20 Jan 23:41 ./
drwxr-xr-x  6 aa  staff   192B 20 Jan 23:41 ../
-rw-r--r--  1 aa  staff   175B 20 Jan 23:41 CMakeLists.txt
-rw-r--r--  1 aa  staff   2.1K 20 Jan 23:41 README.adoc
-rw-r--r--  1 aa  staff   2.1K 20 Jan 23:41 dht.c
-rw-r--r--  1 aa  staff    59K 20 Jan 23:41 pi-and-pico-uart-and-dht-sensor.fzz
-rw-r--r--  1 aa  staff   303K 20 Jan 23:41 pi-and-pico-uart-and-dht-sensor.png
-rw-r--r--  1 aa  staff   409K 20 Jan 23:41 serial-output.png
$

as well as the example code and CMake infrastructure you'll see a README.adoc file and accompany Fritzing and PNG files.

These asciidoc files will render when looking at the code example here in Github but will also get (automagically) imported into the PDF documentation, see "Appendix A: App Notes" in the C/C++ SDK book, along with the example code.

The dht_sensor/README.adoc is probably the best template example to copy. You can find the Fritzing part for Pico here so that you can create a wiring diagram.

from pico-examples.

even without the fritzing, the documentation of how it works is invaluable!

from pico-examples.

even without the fritzing, the documentation of how it works is invaluable!

Oh, agreed!

from pico-examples.

I know that I won't be able to get to this. I will close this now.

from pico-examples.