Generate HTML API documentation using Github Actions

[lukego]

This PR adds a Github Action to automatically build and publish the (nascent) Kons-9 API documentation (#219) in HTML to Github Pages.

Once merged the URL https://kaveh808.github.io/kons-9 should always contain the latest successfully built docs from the main branch of this repository.

This will also provide some additional test coverage in that the examples in the API documentation are automatically verified and the build will fail if they don't produce the expected results.

Could require some fiddling with Github Actions settings. I can look into that if it doesn't work as expected immediately after merge.

This is working on my kons-9 branch:

• Github Action result: https://github.com/lukego/kons-9/actions/runs/5121959800
• Published page: https://lukego.github.io/kons-9

[lukego]

@kaveh808 We need to change Settings -> Pages -> Source to Github Actions.

Could you either do that or give me temporary admin privileges to do so?

Here is how it looks on my fork (the Source: Github Actions part under "Build and deployment"):

Currently the docs are building successfully from the main branch but can't publish to Github Pages yet: https://github.com/kaveh808/kons-9/actions/runs/5126118506

[ghost]

This looks nice. One small nitpick is that some symbols like +ORIGIN+ have use the CL convention for a constant, but are defined with defparameter and labeled in the docs as "variable".

[kaveh808]

@lukego I can't see how to give you admin privileges. Maybe because this is not an enterprise repo?

I made the build change as indicated. Please let me know if it worked.

[lukego]

@kaveh808 Thanks! That did the trick and the docs for the main branch are now live at https://kaveh808.github.io/kons-9/

For more visibility into the updates see the Actions tab (https://github.com/kaveh808/kons-9/actions) and particularly the "Publish to Github Pages" workflow that is now triggered on pushes to the main branch.

This is cool! Changes that affect the documentation, e.g. adding docstrings in api.lisp or including them in regular source files, should automatically propagate to the HTML docs.

[lukego]

One small nitpick is that some symbols like +ORIGIN+ have use the CL convention for a constant, but are defined with defparameter and labeled in the docs as "variable".

Good catch. Having API docs automatically generated from symbols in the Lisp image will make some choices like DEFCONSTANT vs. DEFPARAMETER more significant than they otherwise would be.

[foretspaisibles]

Congratulations, I am eager to try that out! :-)