[oi-dev] Fwd: [OpenIndiana-discuss] Documentation-Project

[Bayard Bell]

Tobias,

Just checking in to make sure you're still with us and see where we can go from here. As you may have gathered from the list, we've had a few fires burning this week. ;->

A few practical questions that would help. First, you've mentioned that you're doing this for a class that you're taking, so I want to make sure that we get back to you on a timeframe that works for your assignment. Second, I'm providing a pretty random sample of links on various aspect of maintaining documentation, but it would be very helpful if you could provide some pointers to people talking about their experience working with Sphinx, as I don't know that I've covered this very well (I saw there's quite a list provided by the Sphinx project, but I haven't had a chance to run through it and see which projects could best speak to our needs). Third, I just want to make sure I've understood you: you recommend and prefer Sphinx, but you've got a project to do, which you're willing to do with us, more or less irrespective of what options we choose. Or are you more comfortable with Sphinx and wanting to find a project that's keen to leverage your knowledge of the product?

I hope we haven't missed the boat with you, and I'd like to express my appreciation for the interest you've taken in our project, the expertise you've brought to the table, your tenacity in following up with us, and your patience in bearing with us.

Kind regards,
Bayard

On 30 May 2011, at 19:49, Tobias Famulla wrote:

> Hi all,
> 
> I thought that Sphinx is better known in the Open-Source-Community, but
> because it's not known by the most of you, it might be easier for you,
> if I explain it shortly.
> Sphinx [1] was original written to write the Python-documentation and it
> is written in Python itself, so it runs on any platform on which python
> 2.6 runs. Nowadays it is widely used, especially  by python-projects
> like Zope, Django, Bazaar and also by Blender for example and it is
> actively developed.
> 
> The software itselfs uses reStructuredText which is very close to
> metawiki-syntax or especially Markdown. It is build modular and
> generates HTML, Gnome- and Windows-Help, man-pages, PDFs and Latex
> automatically and is easy to expand.
> It is also possible to add mathematically formulars, source-code and
> complete API-descriptions. To get an impression of the syntax, you can
> click on the "show source" link in the python or sphinx-docu.
> As I read, there is also a converter from DocBook to reStructuredText
> available, so a converter(or in Sphinx called Generator) to DocBook
> might not be an unsolvable problem.
> 
> In my opinion, I prefer reStructuredText over DocBook and Latex, because
> it is very easy to write with standard-editors(like vim, emacs, ... in
> some with syntax-highlighting, this is true for Latex either) but much
> easier to learn. It is also easy to manage with Mercurial or Git and
> build with hooks or simple Makefiles (of course automatically to all
> formats).
> 
> If you prefer to use pure DocBook or Latex, it is of course ok for me. I
> used Latex some times till now, mostly in university for math.
> 
> Tobias
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 1515 bytes
Desc: not available
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110605/8ce0935a/attachment-0008.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 841 bytes
Desc: This is a digitally signed message part
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110605/8ce0935a/attachment-0009.bin>