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?? _______________________________________________ oi-dev mailing list [email protected] http://openindiana.org/mailman/listinfo/oi-dev
