Implement generation of API documentation from source (using JSDocs or similar)

[happybeing]

The most recent code includes comment headers designed to be suitable for automatic generation of API documentation, based on JSDocs or a similar tool. How good those headers are is untested! :grin:

So it would be very helpful to have at least a basic 'builddocs' command to help fix existing problems with what is there so far and to guide new code to ensure the API docs can be generated without lots of fixing.

[jboxman]

Hi!

I'd like to attempt this if that's okay.

Thanks.

[happybeing]

That would be great, it's all yours. I'll be around and happy to try and answer any questions, but I'm not knowledge about JSDocs.

You will probably find that the code comments, particularly the older code, will need updating but I suggest you leave that to me for now and just let me know what changes are needed as I'm working on several of those files and it will help me get into better habits to have to fix them.

Great to have your help 😄

[happybeing]

@jboxman thanks for the PR now merged and I have generated ./docs using your script and it is looking really nice. I'll leave this issue open for any discussion.

Are you willing to tweak the templates at all? I have only had a brief look, so not sure what we might do, so if you have any ideas please post them here for now. My only thought was I like the navigation on the left.

Anything else to think about or to do?

This is neat :smile:

[happybeing]

Hmm, just found docz. It is more than we need but I'm noting it here in case anyone wants to play with it and see how it compares. It looks slick, easy to deploy, extensible, and is markdown based (MDX).

https://github.com/pedronauck/docz

[happybeing]

Before looking at any alternatives to JSDocs I think it might be worth exploring a bit further what that can do.

For example different templates, this one looks nice:

https://github.com/clenemt/docdash

And then customisations.