Improve documentation site

[adamkewley]

This is a top-level stub issue for documentation.

While Jobson at least has docs, they're not comprehensive nor generated from the source code (which would be a big bonus). As the project gets more features and more external devs start rolling it out to production (we've had a production server internally for 6+ months now), good docs will become more important.

Current problems:

• No "binary" build of the docs is released, so users must browse to the github-IO page - there's no way to download them or deploy them internally somewhere
• No dedicated page for configuration file spec + explanation
• No dedicated page(s) for the HTTP API documentation: the HTTP API documentation is available through the runtime /swagger endpoint but is not available in the static documentation
• Stupid piffy introduction paragraph is too long
• No websocket API documentation at all (!)
• No CLI documentation at all (!) - although basic docs are available through the CLI itself, users might expect it to be in the doc pages
• No case-studies or example-type documentation, where users can see a more complicated (e.g. similar to our prod deployment) build system and configuration file
• No mention of jobson UI (!) - it's a separate project, but that's not necessarily clear to devs

[adamkewley]

• Docs now build into a binary (as of 0.0.19)

[adamkewley]

This also needs to explicitly mention that the console log is the "go to" place for information on server errors (rather than the API)

[mtazzari]

As already stated in the specs docs, it would be great to have detailed docs on all the available expectedOutputs fields and on the data type and parsing functions available (toString, toJSON, toFile, etc..)

Regarding case-studies or example-type documentation, an often useful solution is to have recipes that people can download and personalise.

[adamkewley]

Yeah, I agree. This should be a relatively easy change, so I'll aim to roll it out over the next few days.

[adamkewley]

Side note for docs: Would be useful if parts of the docs were reflected from the source code. The spec, configuration, API etc. are structured java classes: adding some annotations (e.g. "@Description") and having a documentation build step transform the class tree into HTML would prevent needing to edit two places

[adamkewley]

The features mentioned in this ticket are implemented on the master branch.