Documentation Pages - Githubissues

binary-array-ld / net.binary_array_ld.bald

Java library for parsing, validating and managing binary array linked data files, e.g. HDF, netCDF.

Apache License 2.0

0 stars 3 forks source link

Documentation Pages #24

Closed marqh closed 3 years ago

marqh commented 3 years ago

Provide documentation resources via github pages.

implementation suggestions

[ ] add doc build to ghAction pipeline
[ ] provide about and simple usage guide pages
[ ] build code documentation
[ ] on merge to main push built docs to doc branch (?gh-pages)
[ ] on merge to main, push built kotlin artifacts to doc branch, for a download latest page (?same for releases?)
[ ] publish docs via github pages URI
[ ] link binary-array-ld.net subdomain to github pages

simonoakesepimorphics commented 3 years ago

As we're using GH pages, I suggest using the "docs directory" option rather than the dedicated branch option, since (IMO) it requires less maintenance for developers, and lets changes in documentation be identified in the same branches / PRs as the corresponding code changes.

simonoakesepimorphics commented 3 years ago

I've looked into using GitHub actions to upload the artifacts (in particular the CLI JAR as we discussed). We can set up the workflow to upload the new artifact when a commit is pushed to master, however it's not possible to set up a fixed link to it in the documentation because the location of latest artifact is particular to the workflow run (see the Artifacts section here if possible). Also, artifacts created by GitHub actions are only retained for 90 days (docs). Do you have another solution in mind for linking the artifacts in the documentation, for example deploying them to a maven repo?

der commented 3 years ago

Could you use releases for this? So the action would create a new release (based on the current tag). As well has having version numbers there's a built in default path for linking to the latest release /releases/latest.