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

[Ken Gunderson]

On Mon, 2011-05-30 at 20:49 +0200, 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.

Familiar with all those projects but you're correct - not with Sphinx.
Your post was actually first I'd hear of it.

> 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).

After quick review it looks worthy of further consideration.  Low bar of
entry but, like Python, it is very tab/indentation dependent?  That
sometimes can be problematic to maintain for people editing from
different platforms using different editors, etc.

> 
> 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

Sphinx seems to meet requirements.  I think at this point maybe time for
Bayard's gf to take it for a test drive and give us her impressions??