Support for localized API documentation

[mbacovsky]

All rake tasks and apipie controller should support multiple languages

[iNecas]

Looks like a candidate for extracting to a helper method

[iNecas]

also, I would go with 'lang' instead of 'l' to be a bit more descriptive

[iNecas]

Looks good, waiting for some documentation

[vassilevsky]

Let me know if you need help. I'm going to use APIpie for documenting a new API at work, in Russian. Willing to invest time into making APIpie output localizable.

[mbacovsky]

@vassilevsky, It would be really great if you could test this PR and check if the docs are explaining things sufficiently to get going. It would be also helpful to know what setup do you use for your project. I'd appreciate any coments.

[vassilevsky]

I will do this during this week and will let you know if I run into problems.

As regards project setup, which details do you need?
We are running Rails 3.2.18.
We use standard controller methods for the API (no Grape or other API builders).
We render responses with JBuilder.
Our test suite is in RSpec.

[mbacovsky]

@vassilevsky, thanks for the details. This patch shouldn't tighten dependeces of apipie in any way so it should just work. I'm more interested in what tools you use in your translations toolchain (I18n, Gettext, etc.). Sorry, I should have been more speciffic.

[iNecas]

Nicely done! merging now

[iNecas]

0.2.0 released

[vassilevsky]

Congratulations to @mbacovsky !

We only use I18n and only when we have long strings we would like to substitute with shorter ones in code. We write shorter Russian phrases and words right in the code :) We use Ruby 2 so we don't even need to add the magic comments with encoding at the top of the files anymore :)

We also use the gem called russian.

Looks like I will start documenting the API tomorrow.

[mbacovsky]

@vassilevsky, we use FastGettext for our project, but I'll gladly help to tune it for I18n if neccessary. Let me know if you meet any obstacles in localizing API in you environment.

[vassilevsky]

I have to let you know that I haven't yet documented the API with Apipie. The show stopper is our internal company requirement for all documentation to be in Confluence. Because of that, I need to be able to export documentation to Confluence Wiki Markup. Now, that is quite a rare feature. Fortunately, there exists a gem called markdown2confluence. It works great. So, now I need something that can export to Markdown. As far as I know, Apipie cannot do that (yet). So, for now, I just wrote everything in Markdown :)

[mbacovsky]

@vassilevsky, thanks for letting me know. I'm not sure if the extra features apipie offers (ruby API bindings for free, easy to get CLI,..) are worth it for you, but it may be interesting to try to add export to markdown to apipie. It shouldn't be that difficult.

[iNecas]

Yeah, unfortunately we don't support that by now, but you're not the one to ask #63.

There are two approaches that could handle that:

1. having custom views for rendering the md and adding another format (besides html and json): we would need to make sure that the docs, that can be originally written in markdown (things like resource description, would be rendered just for the html https://github.com/Apipie/apipie-rails/blob/master/lib/apipie/resource_description.rb#L34)
2. serialize the apipie docs to https://github.com/apiaryio/api-blueprint-ast and use the tooling that is already available there, such as https://github.com/apiaryio/matter_compiler, that is able to take the api-blueprint-ast and compose the API blueprint, which is technically just special format of the markdown

The 2. seems to be like long-term better solution, as there are other folks using the same API for other purposes, that could be shared

[mtparet]

@vassilevsky @iNecas we're also interested to be able to export Apipie documentation to others common formats used by lot's of services. So happy to help if someone begin to work on this feature.