[Bf-python] Adding help info to scripts (alternative proposal)

[www.stani.be]

Hi Willian,
Adding the help browser is certainly an useful thing.
Unfortunately it's a pitty that you want to implement
in an non pythonic way. Python has already a solution
for this, so reinventing the wheel is a pitty. I'd
like to ask you to really reconsider the
implementation as it will make more sense for regular
python programmers. Otherwise bf-python becomes a
dialect from python, which will demotivate regular
python programmers to play with Blender (this already
a bit the case with get and set methods instead of
using __getitem__ and __setitem__). Normally a python
program would look like this:

__author__  == "Author's name"
__version__ == "version"
__url__     == ("Some site, http://somesite.com",
                "Another site,
http://anothersite.com")
__email__   == "Name, name at email.com"
__doc__     == """\
This script does this and that and this is how we
add help info for it, we just keep writing as many
lines as we want.  About the tags above, there
can be more than one author, link and email tag,
just use a tuple or a list, like done for 'url'
above.

This opens a new paragraph.  Note that you have to
skip one line to separate each
paragraph.

Here's another paragraph."""

(Notice that __url__ is common to use for link,
althought that is of course less important. For me it
could also be __link__, but as we are setting the
standard it could also just be __url__)

The big advantage (besides from being more pythonic)
is that when using more bigger scripts, which consist
of multiple files, or packages you can import the tags
(like author, url, ...) from eachother, so you only
have to update one tag and automatically all the other
tags in the other files are updated at once. (This how
it works in spe and a lot of other existing packages
as well.)
Another advantage is that when you use a python script
not written for blender it might have this information
already and appear nicely immediately in the Blender
help browser.
Please consider this proposal,
Stani

http://spe.pycs.net
http://www.stani.be


--- Willian Padovani Germano <wgermano at ig.com.br>
wrote:

> Hi,
> 
> This is quite fresh, two days old actually, but it
> seems usable 
> already.  It is a script that parses help info from
> installed 
> (registered) scripts and shows it to the user.
> 
> It requires two additions, Blender.Get('homedir')
> and 
> Blender.Get('uscriptsdir') that I committed to cvs
> yesterday, so only 
> those who compile Blender from cvs can test it for
> now.  The script also 
> follows the current theme in Blender, using colors
> from the Text Editor 
> window (bg, text and text highlight) and you can
> scroll text and resize 
> the window.
> 
> To try the script, put it in your scripts dir, open
> it from the Help 
> menu, then choose itself from *its* help menu, since
> the other scripts 
> you have are not yet updated with the format that
> this script expects to 
> find.
> 
> The format is like this, put it in your script and
> it'll be ready for 
> the help browser:
> 
> # <bpy_info>
> # <author>Author's name</author>
> # <version>version</version>
> # <link>Some site, http://somesite.com</link>
> # <link>Another site, http://anothersite.com</link>
> # <email>Name, name at email.com</email>
> # This script does this and that and this is how we
> # add help info for it, we just keep writing as many
> # lines as we want.  About the tags above, there
> # can be more than one author, link and email tag,
> # just add them one per line, like done for 'link'
> above.
> #
> #
> # This opens a new paragraph.  Note that you have to
> # skip two lines,  not only one, to separate each
> paragraph.
> #
> #
> # Here's another paragraph.
> # </bpy_info>
> 
> -- 
> Willian
> 
> > #!BPY
> 
> # """
> # Name: 'Scripts Help Browser'
> # Blender: 234
> # Group: 'Help'
> # Tooltip: 'Shows help information about a chosen
> installed script.'
> # """
> 
> # <bpy_info>
> # <version>0.1 11/02/04</version>
> # <author>Willian P. Germano</author>
> # <email>Bf-scripts-dev mailing list,
> bf-scripts-dev at blender.org</email>
> # <email>Willian, wgermano at ig.com.br</email>
> # <link>Blender.org, http://www.blender.org</link>
> # <link>elYsiun.com, http://www.elysiun.com</link>
> # This script lets users read help information for
> any script registered
> # in the menus, as long as they have been updated to
> include a special
> # section with help info in their source files.
> #
> #
> # To get help for a script, simply select it from
> its group menu.  If it
> # wasn't updated yet with help information in the
> format expected by this
> # script, you'll be offered the possibility of
> loading the chosen script's
> # source file in Blender's Text Editor, since the
> programmer(s) may
> # have written useful comments there for users.
> #
> #
> # But if there is already info available, you can
> use the arrow keys or the
> # mouse wheel to scroll down / up, in case it
> doesn't fit completely in the
> # screen.  Pressing ESC makes the script go back to
> its main screen, Q quits
> # immediately and S loads the script's source in the
> Text Editor.
> # In the main screen, with the groups menus, both
> ESC and Q can be used to
> # exit.
> #
> #
> # Besides the help information, each script's help
> page created by this
> # "Scripts Help Browser" can include buttons with
> internet links and emails.
> # The tooltip in them can tell you where they lead
> to.  Pressing the button
> # should open your internet browser (or email client
> program) automatically.
> # </bpy_info>
> 
> # $Id: sysinfo.py,v 1.4 2004/07/29 12:12:20 broken
> Exp $
> #
> #
>
--------------------------------------------------------------------------
> # sysinfo.py version 0.1 Jun 09, 2004
> #
>
--------------------------------------------------------------------------
> # ***** BEGIN GPL LICENSE BLOCK *****
> #
> # Copyright (C) 2004: Willian P. Germano, wgermano
> _at_ ig.com.br
> #
> # This program is free software; you can
> redistribute it and/or
> # modify it under the terms of the GNU General
> Public License
> # as published by the Free Software Foundation;
> either version 2
> # of the License, or (at your option) any later
> version.
> #
> # This program is distributed in the hope that it
> will be useful,
> # but WITHOUT ANY WARRANTY; without even the implied
> warranty of
> # MERCHANTABILITY or FITNESS FOR A PARTICULAR
> PURPOSE.  See the
> # GNU General Public License for more details.
> #
> # You should have received a copy of the GNU General
> Public License
> # along with this program; if not, write to the Free
> Software Foundation,
> # Inc., 59 Temple Place - Suite 330, Boston, MA 
> 02111-1307, USA.
> #
> # ***** END GPL LICENCE BLOCK *****
> #
>
--------------------------------------------------------------------------
> 
> import Blender
> from Blender import sys as bsys, Draw, Window
> 
> WEBBROWSER = True
> try:
> 	import webbrowser
> except:
> 	WEBBROWSER = False
> 
> PADDING = 15
> COLUMNS = 1
> TEXT_WRAP = 100
> WIN_W = WIN_H = 200
> SCROLL_DOWN = 0
> 
> def screen_was_resized():
> 	global WIN_W, WIN_H
> 
> 	w, h = Window.GetAreaSize()
> 	if WIN_W != w or WIN_H != h:
> 		WIN_W = w
> 		WIN_H = h
> 		return True
> 	return False
> 
> def fit_on_screen():
> 	global TEXT_WRAP, PADDING, WIN_W, WIN_H, COLUMNS
> 
> 	COLUMNS = 1
> 	WIN_W, WIN_H = Window.GetAreaSize()
> 	TEXT_WRAP = int((WIN_W - PADDING) / 6)
> 	if TEXT_WRAP < 40:
> 		TEXT_WRAP = 40
> 	elif TEXT_WRAP > 100:
> 		if TEXT_WRAP > 110:
> 			COLUMNS = 2
> 			TEXT_WRAP /= 2
> 		else: TEXT_WRAP = 100
> 
> def cut_point(text, length):
> 	"Returns position of the last space found before
> 'length' chars"
> 	l = length
> 	c = text[l]
> 	while c != ' ':
> 		l -= 1
> 		if l == 0: return length # no space found
> 		c = text[l]
> 	return l
> 
> def text_wrap(text, length = None):
> 	global TEXT_WRAP
> 
> 	lines = []
> 
> 	if not length: length = TEXT_WRAP
> 	while len(text) > length:
> 		cpt = cut_point(text, length)
> 		line, text = text[:cpt], text[cpt + 1:]
> 		lines.append(line)
> 	lines.append(text)
> 	return lines
> 
> def load_script_text(script):
> 	global PATHS, SCRIPT_INFO
> 
> 	if script.userdir:
> 		path = PATHS['uscripts']
> 	else:
> 		path = PATHS['scripts']
> 
> 	fname = bsys.join(path, script.fname)
> 
> 	source = Blender.Text.Load(fname)
> 	if source:
> 		Draw.PupMenu("Done!%%t|Please check the file
> \"%s\" in the Text Editor window" % source.name)
> 
> 
> # for theme colors:
> def float_colors(cols):
> 	return map(lambda x: x / 255.0, cols)
> 
> # globals
> 
> SCRIPT_INFO = None
> 
> PATHS = {
> 	'home': Blender.Get('homedir'),
> 	'scripts': Blender.Get('scriptsdir'),
> 	'uscripts': Blender.Get('uscriptsdir')
> }
> 
> BPYMENUS_FILE = bsys.join(PATHS['home'], 'Bpymenus')
> 
> f = file(BPYMENUS_FILE, 'r')
> lines = f.readlines()
> f.close()
> 
> AllGroups = []
> 
> 
=== message truncated ===>
_______________________________________________
> Bf-python mailing list
> Bf-python at projects.blender.org
>
http://projects.blender.org/mailman/listinfo/bf-python
> 



		
__________________________________ 
Do you Yahoo!? 
Check out the new Yahoo! Front Page. 
www.yahoo.com