andysworkshop / stm32plus

The C++ library for the STM32 F0, F100, F103, F107 and F4 microcontrollers
http://www.andybrown.me.uk
Other
745 stars 224 forks source link

API Documentation on your webpage #147

Closed hellow554 closed 8 years ago

hellow554 commented 8 years ago

Sometimes, when I want to program something with the library, I don't want to build the docs first and afterwards crawl me through the index. My idea is, that you build the documentation (at least for the last 'release' and the master) and publish it on your website or the github pages. You could use the webhooks for that.

mikepurvis commented 8 years ago

It's not hard to do this yourself— there's an old snapshot of stm32plus docs on my github pages site from ages ago:

http://mikepurvis.github.io/stm32plus/namespacestm32plus.html

Another simple way could be to build the docs automatically as part of travis, and dump them to an Amazon S3 bucket. This would be well below the free tier, so it'd be a no-cost setup to have up-to-date docs online all the time.

A more involved option could be to use RTD/Sphinx, which via Breathe can process doxygen output. This would require a lot more effort to create and maintain, as Sphinx is much more of a "user manual" than a generated API dump.

I looked into all this a little while back. One of the most discouraging aspects is that Doxygen just doesn't handle heavy template usage all that well, so the docs from a template-driven lib like stm32plus are not as meaningful as they might otherwise be.

hellow554 commented 8 years ago

Close in favor of #34