[Doc-SIG] Python docs in reST

[Martin Blais]

On 5/27/05, Felix Wiemann <Felix.Wiemann at gmx.net> wrote:
> Fred L. Drake, Jr. wrote:
> 
> >> * We want an **easy-to-use** documentation system.  Any documentation
> >>   should be renderable by typing "sometool.py input.txt output.html".
> >>   Getting multi-document output should be similarly easy.
> >
> > Again, I think we have this now.  "mkhowto input.tex" is pretty
> > straightforward.
> 
> But it doesn't work out of the box and it's not easy to install.
> 
>     ~ $ cd source/python/python/dist/src/Doc/lib/
> 
>     ~/source/python/python/dist/src/Doc/lib $ locate mkhowto
>     /home/felix/source/python/python/dist/src/Doc/tools/mkhowto
> 
>     ~/source/python/python/dist/src/Doc/lib $ /home/felix/source/python/python/dist/src/Doc/tools/mkhowto libbase64.tex
>     +++ TEXINPUTS=/home/felix/source/python/python/dist/src/Doc/lib:.:/home/felix/tex:/var/home/felix/source/python/python/dist/src/Doc/paper-letter:/var/home/felix/source/python/python/dist/src/Doc/texinputs:
>     +++ latex libbase64
>     *** Session transcript and error messages are in /home/felix/source/python/python/dist/src/Doc/lib/libbase64/libbase64.how.
>     *** Exited with status 1.
>     [snipped error messages]
> 
> Doc/README doesn't tell me what to install to make it work.

indeed, but that's really just a question of packaging.  all that
needs to be done (and i did some of that earlier for one project but
never finished it completely) is to make it independent, give mkhowto
a fancy-looking name like python-build-docs, remove all the stuff
specific to the python doc (they are easy to find from looking at the
makefile, i.e. getting the version, some custom footers and notices,
etc.), and voila.  it's low-hanging fruit.  (i should just shut up and
do it grmmbl.)