[Bf-python] Automatic documentation : ) !

[Willian Padovani Germano]

> IMHO there will be need to harmonize the style of documentation as much
> as possible and it is best left to one or two busy with the [bf-docboard]
> I will wait until this weekend for [bf-docboard] to respond.

Yes, first, internally the Blender Python docs will need to be consistent,
uniform.  But since this is the case for the docstrings in each module, it
is a natural thing to do.

Now keep in mind that this documentation is about programming.   Even
newbies looking at it will have to know the basics of Python (there's plenty
of good guides for that, even for total newbies to programming) before
trying their own scripts, or will have to learn from tweaking with examples,
if they prefer.

So it is at least a little different from the rest of a Blender Manual, we
have to document the API, also, every function and variable there.  And for
this, the best tool is an automatic one, that can be recreated whenever the
API changes.   We didn't get that, but we got pretty close.  This is
something we must do even if there is another source of info, like the
Manual, if the doc guys choose to document bpython on their own.

So that's a choice for the doc board.  Look at our documentation, that is
built from docstrings with some "sugar" added and see if that is good enough
(if it is almost good enough, we just need to add a little more).  The
advantage, again, is that we'll have to do them anyway and that's easy work
with epydoc.

We'll count on the Manual for things like explaining properly what each
object in Blender is: metaballs, lamps, cameras, etc.  And concentrate on
explaining how to access and modify them with Python, hinting at what
interesting things can be done, etc.

> I will post an outline soon and get feedback.
Ok : ).

--
Willian, wgermano at ig.com.br