search

raspberrypi / pico-feedback

25 stars 2 forks source link

docs: cyw43_driver API absent from the PDF #256

Closed slimhazard closed 1 year ago

slimhazard commented 2 years ago

The cyw43_driver API does not appear in the PDF version of the SDK docs. Chapter 4.4.3 is empty.

And the online HTML docs are still at version 1.3.1. So none of the networking APIs are there at all.

I had thought that the details of cyw43_driver had been left out intentionally -- since the tinyusb chapters have always been empty, it seemed that leaving out external libs was policy. Until @kilograham pointed out in this forum post that I could view the API by running make docs in the SDK build directory, to get local HTML, and it is in fact there.

So cyw43_driver was apparently not left out on purpose. I suggest:

It's worth mentioning that the formatting for pico_cyw43_arch in the PDF (chapter 4.4.2) appears to have been a bit botched.

pico_cyw43_arch and cyw43_driver are both important for the PicoW, and since I suspect that many users don't know about make docs, it's hard to learn how they work.

aallan commented 2 years ago

Known issue. We have to do some hacking on the XSLT that takes the Doxygen documentation and turns it into Asciidoc, and there to the PDF. Unfortunately, we're in the middle of another related project and therefore won't be getting to that any time soon. It's unlikely the PDF documentation will get updated before August at the earliest at this point.

aallan commented 2 years ago

@lurch I'm tagging you in this one, but your current priority list stands.

slimhazard commented 2 years ago

What about online HTML for version 1.4.0? Generation from doxygen works fine, the files just need to be transferred over to the server.

I certainly understand about priorities. It would be a shame, though, if SDK devs can't get going with the PicoW because it's hard to read up about how. At least the online HTML would be something to work with until August. Either that or find a way to tell all the world about make docs.

aallan commented 2 years ago

There is a whole appendix in the SDK book about how to build the API documentation. At least I remember writing that appendix, it's probably in the SDK book.

Yes. Updating the API docs Micro site was on my to do list for this week. It unfortunately dropped off the end. Hopefully Monday or Tuesday next week.

lurch commented 2 years ago

Just looking through some old issues, and FYI https://raspberrypi.github.io/pico-sdk-doxygen/index.html got updated to v1.4.0 a while ago.

lurch commented 1 year ago

Closing as invalid, as the SDK API docs are now only at https://raspberrypi.github.io/pico-sdk-doxygen/ and no longer included in the C-SDK PDF.