[Doc-SIG] Lisp oriented docstrings (Manolo's strikes back. )

[Manuel Gutierrez Algaba]

Pity, pity and pity that you don't like the "python-encyclopedia"
idea, anyway... 
\indexauthor is a single idea, unnatributed, so David is not 
the same that : "Author: Walt Disney" 

But anyway, If you really want to mess with lowlevel stuff and that
still is interfering for higher things then I'll propose the definitive
answer to this nasty stuff of Authors,params and so on and so on.

The problem seems how to stablish the low level stuff: spaces,
syntax, colons,... Really nasty in my opinion. Python is not java,
and because of that we have the glorious list and the glorious eval.
Let's use them! 

def function_A( list_A, list_B ):
     """
	author('Guido van Rossum').date('1/1/1999').\
	contributors(["John Doe"]).santi(['\indexpollo',
        '\indexrojo'], radius = 6).arg(1, []).arg(2,[])
     """
Advantages of this approach: 
- Needs no parsing! Just eval(function_A.__doc__)
- No low level details
- Automatical i18n
- You can use default arguments ( author ) for all the 
functions of a module.
- If you know python you know how to write the docs
- All the flexibility and power of python 
- Nice syntax ( if you like python, of course !)
- Absolute extensibility and freedom of use ( you can make
default what you want, and omit what you want ).

author, date .... will return an object, lets name it :
Bandurria. The Bandurria objects get more and more attributions
and it can be affected by global switches when generating the 
final doc. 

def author(self, name):
   b = Bandurria()
   b.name(name)
   return b

the same with date ...

class Bandurria:
     def author(self, name):
          self.name = name
          return self 

the same with date ...


I hope you understand it the first time, if so, let's approve it
and let's face the real interesting thing: SantisimaInquisicion


Yes, MA Lemburgh, Jaja is Spanish and Jiji too, They're the sounds
of the laughter! But , that's low level stuff, not interesting at all!

The eagle seems small when flying high, but in fact when it stands
in the ground is a really big animal.

Regards/Saludos
Manolo
www.ctv.es/USERS/irmina    /TeEncontreX.html   /texpython.htm
 /SantisimaInquisicion/index.html 

  If something has not yet gone wrong then it would ultimately have been beneficial for it to go wrong.