search

exasol / virtual-schemas

Entry point repository for the EXASOL Virtual Schemas
http://www.exasol.com
MIT License
24 stars 23 forks source link

Unify + Improve dialects documentation #380

Closed jakobbraun closed 4 years ago

jakobbraun commented 4 years ago

At the moment each dialect's documentation page is maintained separately. By that often the content seems to be reduced to a minnimum. For example, adding hints on how to find BucketFS user and port #311 need to be added to all pages. Even worse this information must also be reviewd and maintained at all pages in parallel.

This could be simplified by a template system. Therefore we could generate the dialects documents from templates and add shortcodes like [bucket_fs_upload] that the template renderer would then render to the markdown file. We could ensure that the generated version is recent by a maven plugin that breaks the build in CI.

This approach would also facilitate to add badges for the adapter capabilities (#363)

Even more we could generate the tables with the supported data type conversions (example) from a more convenient syntax like yaml. Wh did ever sort such a list in alphabetic order by hand, will like this feature ;-)

tkilias commented 4 years ago

If things repeat, it might be a good idea to extract them into a central document, such that they can't diverge.

jakobbraun commented 4 years ago

we already have that. Now in the docs portal. But the dialects documentations are at the moment as a full tutorial for setting up the dialect. I think this is quite good. As such it should be complete and also contain all the relevant hints.

AnastasiiaSergienko commented 4 years ago

We discussed this ticket and decided not to implement a unified generation for the dialects documentation , because they have too many differences to unify them.