i18n: Make reference documentation translatable

[SunderB]

Aims:

• make the reference documentation (synths, fx, lang, samples) translatable (e.g. suitable for weblate)
• reorganise how documentation is generated, and make it easier to generate the docs in different forms/formats in the future.

Main changes:

doc.rb, i18n-tool.rb and qt-doc.rb have been replaced by new scripts located in /app/server/ruby/bin/doctools:

• extract-reference.rb Processes the documentation data for synths, lang, fx, samples and extracts it into JSON files (in /etc/doc/reference/). These are the files that will be translated. This is in some way inspired by how Godot Engine uses XML to extract reference/class docs: https://github.com/godotengine/godot/tree/master/doc/classes, https://github.com/godotengine/godot/blob/8f7f5846397297fff6e8a08f89bc60ce658699cc/doc/translations/extract.py.
• i18n-tool.rb Does the same job as before, but also applies and updates translations of the reference .json files

qt-doc.rb has been split out into different scripts

• create-html.rb Generates HTML pages for the tutorial and all the doc sections, and JSON tables of contents for each language, to /etc/doc/generated_html/
• generate-qt-doc.rb Copies the HTML files to the /app/gui/qt/help/ folder, and writes the indexes to ruby_help.h
• generate-book.rb Generates single page HTML documents for each language & section into /app/gui/qt/book/
• generate-site.rb (Not fully implemented, possibly could be split into a different PR) Generates the source files to be used by Jekyll to generate a documentation website

Documentation translation files are now located in /etc/doc/translations/(tutorial/reference)

This is just a proof of concept/first implementation.

[samaaron]

This looks like interesting work.

Given that it looks to be a rather sizeable PR, would it be at all possible to document what specifically it's aiming to do, what design decisions you took and what other options there might have been (if any) that you considered but rejected in favour of this approach.

I'd certainly like to get more of an understanding of what this is doing and what new code we'd have to undertake to maintain if we were to merge this.

I also believe that @ethancrawford has done some work in this space, so it's probably worth getting together to see if there's any crossover and opportunities to collaborate :-)

[ethancrawford]

Hey @SunderB 🙂 As Sam has mentioned, I actually began investigating this same task a little while ago... I'm hoping there's a way we can implement this feature without putting aside too much of our individual work - it would be great to have a chat about our different approaches and the best way forward. Is there a good way for us to communicate off GitHub? Happy to chat by plain email, or even have a video call somewhere.

[SunderB]

Hi @ethancrawford :) Yeah, it would be cool to have a chat about approaches to this :) The best way to communicate (outside of GitHub or in-thread) is either via Discord, or email probably. I could send you an email if you want?

[SunderB]

Closing this for now, as this functionality has now been implemented in a different way. (See #2956)