Generate docs automatically

[Bisaloo]

I was trying to find the changes made as part of #14 but the git history is quite difficult to navigate at the moment. One reason for this is that actual changes are tangled with update of the docs build time within a single commit (e.g., be3a412).

Additionally, the process to generate docs is not documented at the moment. This makes it difficult for an external user to contribute or for a new maintainer to take over (if you ever get bored of this project or if you have other commitments that force you to let it go).

I believe a good option to:

• make the git history clearer
• make the doc building process apparent

would be to use a GitHub Action to automatically generate the docs. The JSDoc README suggests this action: https://github.com/andstor/jsdoc-action.

This issue is part of openjournals/joss-reviews#3948.

[bramvandijk88]

I am sorry the git history is a bit of a mess, this project was much more extensive than I initially anticipated. I have heard pretty scary stories about trying to clean up git histories, so I am not very enthusiastic about doing this.

In any case, the documentation process is already fully automated, but I prefer to use my own workflow (and a custom bash script) for this. The script make_bundle.sh bundles, tests, and documents all functions within Cacatoo. Every time I think it is time to roll out a new distribution (i.e. a one-file bundle), I run this script to ensure everything is up-to-date. The JSdocs that are generated with this script can be found on the Github website: https://bramvandijk88.github.io/cacatoo/

I feel like I may be a bit old-fashioned in some regards, but I am slightly allergic to integrating it fully with Github Actions. I am confident that, if I ever need to yield the project to another user, I will be able to explain my workflow to this person.

[Bisaloo]

Okay, fair enough for the GitHub Action. This is ultimately your choice.

I do believe it is however necessary to explicitly document in the repo how you re-generate the docs (i.e., run make_bundle.sh). The CONTRIBUTING.md guide might be a good place for it.

Yes, I agree trying to re-write git history is generally dangerous and should only be done as a last resort. A simple "fix" for the future would be to try to always run make_bundle.sh in a separate commit (if possible).

[bramvandijk88]

Yeah, I will try and be more careful with making smaller commits in the future. Some of them got lumped together because I changed too much at the same time, and I'm sorry if things got a little messy.

The README.md already mentioned how the documentation is generated, but I've also added it to CONTRIBUTING.MD just in case someone would miss it.

[Bisaloo]

Thanks! This issue is resolved as far as I'm concerned.