gnumed-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Gnumed-devel] small Sphinx demo


From: Sebastian Hilbert
Subject: Re: [Gnumed-devel] small Sphinx demo
Date: Thu, 11 Sep 2008 11:10:30 +0200
User-agent: KMail/1.9.9

On Donnerstag 11 September 2008, Gour wrote:
> Hello list!
>
> I tried to provide a small demo to show you how can GNUmed docs
> generated with Sphinx look like since there are no new bugs and I cannot
> test and put my bugs2LP script in work. :-)
>
>
> So, for the sake of experiment or let's say as a small 'proof of
> concept' I picked few wiki pages from the 0.3.2 tarball - those under
> First Steps section.
>
> In order convert them to *.rst files I had too much problems :-(
>
> Pandoc converter is used here daily, but it failed...I was googling and
> asking to find some other html2rst script, but all failed with some
> utf-8 encoding until I went to inspect twiki's generated *.html sources
> to find out that iso-8859-15 encoding is used :-/
>
>
> Please, we're in 21st century (aka Unicode) - no more those ancient
> iso8859-X encodings!
>
>
> So, after passing *.html through iconv to convert them to utf-8, i had
> to find some additional script and converted them into *.rst files.
>
> Then running sphinx-quickstart and answering few questions I got
> template to populate with the source files.
>
> Here it is (index.rst):
>
> .. GNUmed manual (sphinx test) documentation master file, created by
>    sphinx-quickstart on Wed Sep 10 19:06:33 2008.
>    You can adapt this file completely to your liking, but it should at
> least contain the root `toctree` directive.
>
> Welcome to GNUmed manual (sphinx test)'s documentation!
> =======================================================
>
> Contents:
>
> .. toctree::
>    :maxdepth: 2
>
>    StartingGnumed
>    GnumedUserInterface
>    BasicPatientHandling
>    BasicProgressNotes
>    BasicEmrStructuring
>
> Indices and tables
> ==================
>
> * :ref:`genindex`
> * :ref:`modindex`
> * :ref:`search`
>
>
> I added the five sources to the list - that's all.
>
> Moreover, Sphinx generates Makefile for free and then issuing:
>
> Then I edited *.rst files a bit - only chopped out headers & footers
> generated from twiki - nothing else!
>
> Time to generate docs with 'make html' and 'make latex' and then in
> latex dir running 'make all-pdf'.
>
> So simple and everything can be done easily within cron job on the
> server.
>
Nice work. Thanks for being persistent. From here on out what is your proposed 
workflow. Any chance wiki can be used as a base for your work or do you 
recommend to work on the manual section exclusively with rst files.

To sum up our dispute I understood it like this. Wiki is by far the easiest 
(not the prettiest) way to edit something and have it show up instantly 
without any other local tools.

So some GNUmed members exclusively edit documentation in environments where 
all they have is an internet browser. No USB drive. No VCS . They could edit 
in notepad and email it to themselves and later check it in but they do not 
want that. they want results on the screen by hitting the save button in the 
wiki.

For a to be printed manual your approach may be cleaner. Do you think the 
following workflow can be used ?

Wiki --> edit over months until a release --> transfer manual from wiki to rst 
and tidy up --> release manual and software.


> Here you can see results:
>
> http://atmarama.org/gnumed/ and
>
> http://atmarama.org/gnumed/gnumed.pdf
>
> (My name on the docs is result of answering the 'author' question, but I
> do not pretend to own the copyright being greatly afraid of
> Sebastian.) :-)
>
>
> Let the flame begin...
>
>
> Sincerely,
> Gour



-- 
Sebastian Hilbert 
Leipzig / Germany
[www.gnumed.de]  -> PGP welcome, HTML ->/dev/null




reply via email to

[Prev in Thread] Current Thread [Next in Thread]