[GNC-dev] Porting the Tutorial & Concepts Guide to ReadTheDocs.org

[Rob Gowin]

> On Apr 25, 2020, at 2:24 AM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> Hi Rob,
>  
> Thanks for running this experiment.
>  
> The stylesheet used by ReadTheDocs is much more modern than ours and indeed looks much nicer for online consumption. Even the pdf is cleaner.
>  
> On the other hand I also have a few concerns/questions:
> 1. How would a translation flow look like with asciidoc ?
> 2. Can it support a single master document including sections that should only appear for certain translations ?
> 3. ReadTheDocs is a hosted service. That's a big change from our current philosophy to self-host as much as possible. Are there self-hosting options ?
>  
> Regards,
>  
> Geert

Hi Geert, 

First off, yes, the documentation can be self hosted. I’ve done that here: https://gnucash-docs-test.codesmythe.net/index.html <https://gnucash-docs-test.codesmythe.net/index.html>. It uses an older stylesheet, so looks a little different, and there’s no PDF there. I have generated a PDF similar to the ReadTheDocs one locally. Note that this experiment uses files in the reStructuredText format, not asciidoc. The reST files are generated from the DocBook files using pandoc.

For translation: The underlying tool used by ReadTheDocs is the Sphinx Python Doc Generation Project. Their I18N flow is described here: http://www.sphinx-doc.org/en/master/usage/advanced/intl.html <http://www.sphinx-doc.org/en/master/usage/advanced/intl.html>. I’m no expert in the area, but seems it does support a single master document. I don’t know about sections that should only appear for certain translations.

I’ll jump on IRC sometime this week to discuss translations in more detail. 

Regards,

Rob