[Qgis-developer] [hackfest] documentation tasks

[Tim Sutton]

Hi

On Thu, Apr 5, 2012 at 4:23 PM, Paolo Corti <pcorti at gmail.com> wrote:
> Hi all
>
> On Fri, Mar 30, 2012 at 11:02 PM, Tim Sutton <lists at linfiniti.com> wrote:
>>
>> Yes if (when!) we move to gettext I'm afraid it will be quite a job in
>> the beginning for translators to migrate their content (you can do it
>> comfortably using QtLinguist from that point on though which is nice.
>>
>
> I do not know QtLinguist, will give a look for sure before the HF.
>

Good -  I or Werner can show you at the HF too...

>> Also I would really like to see some consolidation of the various
>> docs, work on our own custom sphinx theme (would be a nice job for
>> html wizards) - I already made a simple QGIS one but there are lots of
>> features needed to replicate the output of the LaTeX manual as closely
>> as possible. Also migrating the t2t documentation to sphinx would be
>> nice.
>
> I have created a (very basic) Sphinx project infrastructure, with support for
> Internationalization. I have also migrated a couple of .tex files to .rst,
> and tested the infrastructure with Italian .po files.
> You can find everything here [1]: you can easily build the solution by
> running the ./build.sh script and access to the EN and IT version, both
> builded under _build/html.
> Or you can check it online [2], but just the EN (master) version, as RTD
> does not support internationalization at this time.
>
> By the way, I have been using your qgis-theme from the Governance
> project, and will send you a pull request with some slight modifications for
> supporting the .rst rules I have been used (actually only rendered with
> the html builder, need to figure out how to get the same with pdf).
>

Ok - please pull again from teh governance theme as I integrated some
of the features from my company private theme. In particular styles
for :kbd: :menu-selection:, ..notes:: etc. There are still lots more
of these needed to provide the range of options we have in the LaTeX
docs but I think most things will be possible in the html verison
anyway.

>> I also wanted to raise the idea of moving all the context help stuff
>> into sphinx and away from the current 'loose files' system  - I used
>> this approach on a different plugin and it worked *really* nicely, its
>> much simpler for translators and the context help and the user docs
>> can be much more closely intertwined.
>>
>
> Will give a look at this.
>
> Checklist of things to do for me, before and during the HF in Lyon:
>
> * solve problems with .pdf output
> * using Intersphinx to tie various QGIS documentation projects

Good - and maybe also look at consolidating some of theme where it
makes sense....

> (basically the CookBook and the Governance project at this time, I am
> not aware of other ones)
> * giving a try to pootle
> * giving a try to QtLinguist
> * testing Sphinx for context help
> * consolidate editor workflows (both with gettext or with tools like
> gtranslator and pootle)

Yes to start with at least I think we should support / document a few
different ways for translators to work so we can find which is
preferred.

> * create an ad-hoc python script for migrating latex doc to .rst (I
> have already some idea, in this respect)

This will be great

> * migrate the documentation
> * consolidate the build script (build.sh) and use it live on QGIS site
> for putting the whole thing in production

Great!

Regards

Tim

>
> let me know your ideas and give me some feedback, thanks :)
>
> p
>
> [1] https://github.com/capooti/qgis-sphinx-doc
> [2] http://readthedocs.org/docs/qgis-sphinx-doc/en
>
> --
> Paolo Corti
> Geospatial software developer
> web: http://www.paolocorti.net
> twitter: @capooti
> skype: capooti



-- 
Tim Sutton - QGIS Project Steering Committee Member (Release  Manager)
==============================================
Please do not email me off-list with technical
support questions. Using the lists will gain
more exposure for your issues and the knowledge
surrounding your issue will be shared with all.

Visit http://linfiniti.com to find out about:
 * QGIS programming and support services
 * Mapserver and PostGIS based hosting plans
 * FOSS Consulting Services
Skype: timlinux
Irc: timlinux on #qgis at freenode.net
==============================================