[Top][All Lists]
[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