Druid SQL API documentation refactor

[demo-kratia]

Refactor the Druid SQL API documentation to make easier to browse.

Preview: https://druid-git-druid-sql-api-doc-refactor-demo-kratia.vercel.app/docs/api-reference/sql-api.html

This PR has:

• been self-reviewed.

[vtlim]

LGTM 🦖

[gianm]

This PR dropped the "Errors" section, which is important due to the note about how to detect truncated responses. We need to re-add it in an appropriate place:

Errors

Errors that occur before the response body is sent will be reported in JSON, with an HTTP 500 status code, in the
same format as native Druid query errors. If an error occurs while the response body is being sent, at that point it is too late to change the HTTP status code or report a JSON error, so the response will
simply end midstream and an error will be logged by the Druid server that was handling your request.

As a caller, it is important that you properly handle response truncation. This is easy for the object and array
formats, since truncated responses will be invalid JSON. For the line-oriented formats, you should check the
trailer they all include: one blank line at the end of the result set. If you detect a truncated response, either
through a JSON parsing error or through a missing trailing newline, you should assume the response was not fully
delivered due to an error.

The PR also changed language for csv from this:

Comma-separated values, with one row per line. Individual field values may be escaped by being surrounded in double quotes. If double quotes appear in a field value, they will be escaped by replacing them with double-double-quotes like ""this"". To make it possible to detect a truncated response, this format includes a trailer of one blank line.

To this:

Returns a comma-separated values with one row per line and a trailing blank line. Returns the HTTP header Content-Type: text/csv.

It dropped the rationale for the trailing blank line: "to make it possible to detect a truncated response". This should be added back in, because it's really important. Otherwise people may not realize their response is missing some results due to an error.