rethinkdb / rethinkdb/docs

Better multi-language support in the build system

Open
#710 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
CSS
Stars
118
Forks
161
PR merge metrics
No merged PRs in 30d

Description

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?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by examining the Jekyll build path that produces the final documentation files and determine where a preprocessing or plugin hook could be added. Define how the per-language tags and proposed {{#lang}} tag should render, then verify that one source page can replace the three synchronized copies.

Written by the indexing model from the issue text.

Assessment

Tech stack
jekyll
Domain
build-system, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.