search

microsoft / pxt

Microsoft MakeCode (PXT - Programming eXperience Toolkit)
https://makecode.com
MIT License
2.1k stars 584 forks source link

better documentation for block help plumbing in extension #9880

Closed tballmsft closed 8 months ago

tballmsft commented 8 months ago

Extension authoring docs are way out-of-date with respect to block help. Richard's extensions for pxt-arcade show the way:

https://github.com/microsoft/arcade-character-animations

Jaqster commented 8 months ago

Just to add a bit more context here. When you click on an extension block and select "Help", you would expect the side docs to open a reference article (just like they do for mainline blocks).

image

But instead you get redirected to the extension's readme - https://makecode.microbit.org/pkg/microsoft/pxt-neopixel

Jaqster commented 8 months ago

Not sure this is @ganicke's bug - feels like this is something we should start requiring of all extension authors...

tballmsft commented 8 months ago

It's not a bug - we need better documentation of how to use the existing features for documenting blocks in an extension served from GitHub. I was not able to achieve success (like Richard did) via https://makecode.com/extensions/github-authoring

ganicke commented 8 months ago

This all works due to the magic of the github: prefix in the jsDoc %help attribute. I will add some info discussing this in that page. This help URL routing was added in #7406, #8735.

//% help=github:arcade-character-animations/docs/set-character-state