[Sugar-devel] Sugar docs

[Simon Schampijer]

On 02/23/2012 05:45 PM, Walter Bender wrote:
> On Thu, Feb 23, 2012 at 10:47 AM, Walter Bender<walter.bender at gmail.com>  wrote:
>> On Thu, Feb 23, 2012 at 10:05 AM, Simon Schampijer<simon at schampijer.de>  wrote:
>>> On 02/20/2012 04:08 PM, Bastien wrote:
>>>>
>>>> Hi Simon,
>>>>
>>>> Simon Schampijer<simon at schampijer.de>    writes:
>>>>
>>>>> is this [1] the latest version of the Sugar docs? What is the current
>>>>> process for updates (e.g. the upcoming 0.96). Is there someone working on
>>>>> that end? There were questions here at the GNOME doc hackfest [2] what
>>>>> Sugar is doing for documentation and I am not sure if I am fully up to
>>>>> date.
>>>>
>>>>
>>>> At the SugarCamp in Paris, I brievely mentioned readthedocs:
>>>>
>>>>    http://readthedocs.org/
>>>>
>>>> Florent Pigout told me about this service, which looks quite
>>>> nice.   Maybe the Sugar community could use something like this
>>>> instead of FlossManuals?  FM may be suitable for end-users docs
>>>> but not that much for developers docs.
>>>>
>>>> Best,
>>>
>>>
>>> GNOME does use mallard [1] for their documentation in the docs (yelp). The
>>> concept of "topic-oriented" documentation is nice, I think. Furthermore
>>> using the same tools as GNOME could help in people doing documentation in
>>> both projects. When people want to update the current floss manuals they
>>> could maybe evaluate this first.
>>>
>>> We could use mallard as well for API docs, see for example Tomeu's work on
>>> documenting the Python API docs from introspection [2], the current API
>>> documentation looks rather outdated [3]. Would be a nice project for someone
>>> to work on it.
>>>
>>> Regards,
>>>    Simon
>>>
>>> [1] http://projectmallard.org/
>>> [2]
>>> http://blog.tomeuvizoso.net/2012/02/progress-on-generating-python-api-docs.html
>>> [3] http://doc.sugarlabs.org/epydocs/
>>>
>>> _______________________________________________
>>> Sugar-devel mailing list
>>> Sugar-devel at lists.sugarlabs.org
>>> http://lists.sugarlabs.org/listinfo/sugar-devel
>>
>> Just started a simple example of mallard for Turtle Art. I have to
>> admit I enjoy writing documentation in emacs much better than using a
>> WYSIWYG editor. +1 to mallard.

There seem to be modes for gedit and emacs around.

>> --
>> Walter Bender
>> Sugar Labs
>> http://www.sugarlabs.org
>
>
> I didn't see it anywhere in the basic mallard docs, but is there a
> decent i18n schema? In the case of TA, ideally I could reuse all the
> existing help strings from the .po file. That'd cover the bulk of what
> I'd need in the manual. I also need to look into generating svgs by
> language for the manual.

Maybe those answers a few questions about this matter:

http://projectmallard.org/1.0/i18n.html
http://projectmallard.org/1.0/l10n.html

> Do we have a yelp Sugar activity?
>
> -walter

We have the help activity, which we use to display the help pages. I did 
gave it a quick shot and created a few mallard files with the 10 minutes 
example [1]. Then I processed those to html with 'gnome-doc-tool html 
<directory with mallard files>'. And tadada: we have html documentation 
we can use in any Browser (or a webkit view in the help activity).

Regards,
    Simon

[1] http://projectmallard.org/about/learn/tenminutes.html