[pyPYME-Giotto] [GIOTTO] Gestion de los manuales de usuario

[Jose <coo...@py...>]

Hola,

Por iniciativa de Marcelo he estado pensando acerca de c=C3=B3mo integrar l=
os
manuales de usuario de cada m=C3=B3dulo desarrollado y he llegado a las
siguientes conclusiones:

	1) la documentaci=C3=B3n suele localizarse bajo el men=C3=BA 'Ayuda'
	2) la documentaci=C3=B3n no deber=C3=ADa incluirse en la 'barra de m=C3=B3=
dulos' ya
que no se trata de un bloque funcional (ni presenta, como es l=C3=B3gico, u=
n
'=C3=A1rbol de operaciones') sino que es un complemento (a=C3=B1adido o com=
o
queramos llamarlo) informativo
	3) cada m=C3=B3dulo deber=C3=A1 llevar asociado, de alguna forma, un 'manu=
al de
usuario'
	4) la documentaci=C3=B3n deber=C3=ADa desarrollarse de forma independiente=
 al
c=C3=B3digo. En teor=C3=ADa por personal no t=C3=A9cnico. Esto podr=C3=ADa =
reflejarse en un
=C3=A1rbol SVN propio (p.e.
http://dev.pypyme.org/svn/doc/user_manual/[charon|portia|umbriel|...])
	5) no hemos decidido el formato de la documentaci=C3=B3n. En su momento se
discuti=C3=B3 (e incluso vot=C3=B3) pero nadie parece haberse interesado po=
r
desarrollar este tema
	6) para integrar la documentaci=C3=B3n en el 'Centro de Control' habr=C3=
=ADa que
decidir d=C3=B3nde instalar la documentaci=C3=B3n (me refiero al equipo del
usuario pyPYME), ver NOTA 1, y dise=C3=B1ar un proceso que lo integre en la
estructura de men=C3=BAs del 'Centro de Control', ver NOTA 2.

NOTA 1: La elecci=C3=B3n del directorio donde instalar la documentaci=C3=B3=
n
presenta un problema:

	- por una parte, desde el punto de vista del usuario, ha de estar
integrada dentro de la aplicaci=C3=B3n (debe localizarse dentro del =C3=A1r=
bol
org.pypyme)
	- por otra parte, desde el punto de vista de desarrollo, no debe
mezclarse con el c=C3=B3digo (no debe localizarse dentro del =C3=A1rbol
org.pypyme)

Para superar esta dificultad podemos:

	1) asumir que el proceso de instalaci=C3=B3n crear=C3=A1 un directorio 'ma=
nual'
justo debajo del directorio ra=C3=ADz del m=C3=B3dulo que documenta y copia=
r=C3=A1 ah=C3=AD
el fichero o ficheros que formen el manual de usuario
	2) para probar su funcionamiento dise=C3=B1aremos un test que, para un
m=C3=B3dulo dado:
		a) crear=C3=A1 el directorio 'manual'
		b) copiar=C3=A1 el contenido del directorio
[...]/trunk/doc/user_manual/[m=C3=B3dulo]/ al directorio 'manual' creado en
el punto a)
		c) lanzar=C3=A1 el 'Centro de Control'
		d) al finalizar el test, vaciar=C3=A1 y eliminar=C3=A1 el directorio crea=
do en
el punto a)

NOTA 2: Propongo a=C3=B1adir un submen=C3=BA 'Ayuda', de primer nivel (fijo=
, parte
del dise=C3=B1o del men=C3=BA del formulario 'Centro de Control' al igual q=
ue el
submen=C3=BA 'Fichero'):

	Fichero | [m=C3=B3dulos: Charon|Portia|...] | Ayuda

y dentro del men=C3=BA Ayuda:

	Manuales
		Datos Generales
		Ficheros Maestros
		Tesorer=C3=ADa
		...
	-
	Acerca de...

donde la composici=C3=B3n del men=C3=BA 'Manuales' (inicialmente vac=C3=ADa=
) se
realizar=C3=ADa din=C3=A1micamente, analizando los ficheros 'deploy.py' de =
los
m=C3=B3dulos. Para ello podr=C3=ADamos utilizar una nueva entrada que espec=
ificase
la informaci=C3=B3n necesaria:

	manual =3D {
		'title'   : 'Tesorer=C3=ADa',  # t=C3=ADtulo a mostrar en el men=C3=BA
		'path'    : 'manual',     # relativo al directorio ra=C3=ADz del m=C3=B3d=
ulo
		'filename': 'index.html', # o manual.pdf o el que sea
	}

=C2=BFQu=C3=A9 os parece esta propuesta?

Saludos,
Jose