[Bf-python] Exppython API docs

[Willian Padovani Germano]

Hi again,

An update on the documentation effort.

First, there *is* a simple flag to epydoc that makes it only generate
the public part, not the private one that we don't need.  As my grandma
says, "if it were a snake, it would have bitten me".  This works well
enough, though the frames version still has links for private parts in
the two left frames.

To generate docs from the three files in doc/, I'm using something like:

epydoc -t Blender.py -n "Blender" --no-private Blender.py Camera.py
Lamp.py

I'll add a comment to Blender.py about it, later we can have a README
file there for info on how to generate the docs.

The work so far is to create the fake .py files and sync them with the
docstrings in the resp. .c or .h module file (.h once we clean this
header mess).  I'm not keeping exactly the same docstrings in both.  For
the API docs I'm writing more info and using the special tokens to mark
parameters and return values.  A look at Camera.py and Camera.h can
examplify this.

** Important ** : there are inconsistencies in 2.25 that made us
duplicate some function names, like .Get and .get for the modules.  I'm
not documenting the .get() one, only the preferred .Get().  This is of
course a way to recommend the use of the better interface without
breaking older scripts.  It won't solve all matters, but will help a
little bit, and we don't need to show the same thing twice...

After working for a while with documentation (argh!), it does seem now
that the API docs won't fit as general documentation for scripting in
Blender, but rather as what API refs are: complete references, that more
advanced users may consider the one and only resource.

Ramanan Selvaratnam is right about the need for better integration of
user-friendly scripting docs and the Blender Manual being written.  For
the manual, something more like what the 2.0 manual has is the way to
go.  The API ref will be the best source for doc writers about
exppython, once finished -- and can even become an appendix of the
manual.

Of course, the API ref will also substitute the current 2.25 one at the
site and become one of the basic Blender docs.

--
Willian, wgermano at ig.com.br