search

rethinkdb / docs

RethinkDB documentation
http://rethinkdb.com/docs
Apache License 2.0
117 stars 170 forks source link

Better multi-language support in the build system #710

Open deontologician opened 9 years ago

deontologician commented 9 years ago

Right now we need 3 identical copies of each documentation page, which need to be kept in sync. This is really error prone, and I'm sure super annoying for @chipotle. With the upcoming creation of an official java driver (rethinkdb/rethinkdb#3930) slated for 2.1, the work is about to increase 33%.

Ideally, what it would be really nice to see are some custom tags that we can pre-process into the final files that jekyll uses (if there's some way to make this a jekyll plugin, even better)

Hypothetically:

In the {{#py "python"}}{{#rb "ruby"}}{{#js "javascript"}} driver, we do things like ...

{{#py}}
The python driver uses tornado underneath, so we create generators...
{{/py}}
{{#rb}}
Eventmachine is a wonderful way to do magical delightful ruby things...
{{/rb}}

Having per-language tags as above would be a nice start. Obviously there are some more convenient things we could do, like having a special tag like {{#lang}} that outputs the current language's name, since that will probably be common.

@mglukhovsky @AtnNn thoughts?

mglukhovsky commented 9 years ago

@deontologician: I think this is a very important discussion to have. I have a lot of ideas on this, but not a lot of time to write them up now, but I'll revisit this as soon as possible.

Your proposal seems reasonable. I'd like to find an example of a document where the multi-language docs diverge significantly, because while I believe that the syntax you're proposing makes complete sense, I'm worried that there are several documents where this syntax would make the source document incredibly complex (especially in the API docs).

@chipotle, do any examples come to mind, or does a syntax like this seem reasonable?

chipotle commented 9 years ago

It seems reasonable. The big caveat is the API docs, as you mentioned -- it would make the source document complex, but at the same time that's where this might be the most helpful, since the API docs are nearly-identical text with language-specific examples. Although I would probably add a {{#cc "camelCase" }} tag or something similar that outputs camelCase or camel_case depending on the language chosen, because doing that in text with a series of conditionals would get very verbose very quickly.