Developer documentation with Doxygen

[ghost]

Hello Open Quantum Safe.

I was wondering if we should update our internal and external documentation to use Doxygen?

This may be helpful for new contributors.
We could have something similar to what LLVM is doing for their documentation.

Any thoughts?

[bhess]

For libOQS there is already Doxygen documentation generated (make gen_docs), but the online documentation uses a different template. I agree that something similar would be useful for the other projects.

[baentsch]

This may be helpful for new contributors.

It might -- but considering we have it for liboqs and no-one noticed it was broken for a very long time doesn't make me think too many people use doxygen documents as primary "inroad" to OQS.

To help potential new contributors, what about the idea to more diligent tag issues, e.g., "Good first issue" or "Help wanted" - and in so tagging maybe add a few "getting started" ideas/pointers to those issues? Maybe combined with an overview page at www.openquantumsafe.com listing projects, their interdependence (PQClean -> liboqs -> oqsprovider -> nginx -> ...) and areas where help would be welcome. Oh, and commitment by Committers and Maintainers to help aspiring new contributors would be good too :-)

[dstebila]

We do have doxygen for the documentation of the public API. I've never known how much it was used, and as Michael points out no one noticed it broken for a while.

I'm not sure that doxygen makes for good general documentation -- how-to's, examples, etc. So the stuff on openquantumsafe.org uses a different template (just the docs) and is manually written. Although a few sub pages of openquantumsafe.org are thin wrappers around doxygen-generated files.

I am not wedded to any particular set up, so if you all think of a better set-up, go for it. I've just moved the Github repo for the OQS website from my private account to the OQS Github org, it's now available at https://github.com/open-quantum-safe/www. Feel free to poke around and think about changes. Note that currently the website is still hosted on my personal server with no automated deploy; something to change eventually, but for now I have to do deployments manually.