Documentation & Release workflow

[simonoakesepimorphics]

Fixes #24

• Added release workflow triggered by tagging the master branch.
• Added GitHub pages. Preview
• Refactored context and alias into separate concepts - I think this is more organised and makes them easier to understand.

This requires GH pages to be activated on this repo using the branch: master and /docs settings. Some links might need tweaking depending once the GH pages are live.

To Do

• [ ] Javadoc

[simonoakesepimorphics]

@marqh I've set up the Javadocs for the core and NetCDF modules to be built by dokka in their respective target directories. Do you have a preferred way to publish these?

[marqh]

Hello @simonoakesepimorphics

many thanks for preparing this content, I think this is looking good.

I am going to avoid discussions on what further information could be included for follow up tickets and focus on this content and the mechanics of publishing

regarding:

Do you have a preferred way to publish these?

I would like to publish these through github pages. once we are happy with the content we can then provide a dedicated subdomain of binary-array-ld.net to provide identity. i think that http://kotlin.binary-array-ld/net might work, what do you think?

Previously i have used a dedicated branch, such as gh-pages, for the documentation and publishing. This proposes using master and docs instead. Please could we just explore these options and why we would pick one over the other, so that i am confident of any implications?

I am totally ready to merge this content and turn on github pages on the repository once we've explored the branch question

I'll add any content thoughts as further comments if they arise, expecting further tickets on documentation content to be set up. Many thanks mark

[simonoakesepimorphics]

@marqh Publishing Javadoc (especially Dokka) is relatively new to me so if you have a plan in mind that's great, I will try to do whatever we need to implement it. GH pages or a subdomain sounds OK.

One limitation with Dokka + Maven is that it doesn't have multi-module support, so I will need to set up the link between the NetCDF and core packages by configuring the URL where the core package docs are hosted. This will be a very minor change in the pom.xml but requires some finality on the publishing approach. I am happy to revisit this once we're certain about that.

With regard to the location of the doc content, I prefer to use the docs directory rather than a branch because it makes it easier to identify code changes with the corresponding documentation changes. In the same way as I might expect to find both code changes and automated tests in the same branch / PR / merge, I find it helpful to see the documentation changes in the same place as well. This is not possible in the branch mode, and I find that having to switch between branches to write documentation / compare it to the code creates unnecessary friction for the developer. That's just my preference, I don't mind being overruled / convinced otherwise.

[marqh]

I've done some reading and gh pages on master+docs seems fine and sensible

i have enabled this on the repo now. i assume that this is good to merge now, and the github pages will pick it up

shall we agree to merge and check out the serving? is that okay with you @simonoakesepimorphics?

[simonoakesepimorphics]

@marqh Yes, that will be fine.