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

[maram <mam...@gm...>]

Jose wrote:
> Hola,
> 
> Por iniciativa de Marcelo he estado pensando acerca de cómo integrar los
> manuales de usuario de cada módulo desarrollado y he llegado a las
> siguientes conclusiones:
> 
> 	1) la documentación suele localizarse bajo el menú 'Ayuda'
> 	2) la documentación no debería incluirse en la 'barra de módulos' ya
> que no se trata de un bloque funcional (ni presenta, como es lógico, un
> 'árbol de operaciones') sino que es un complemento (añadido o como
> queramos llamarlo) informativo
> 	3) cada módulo deberá llevar asociado, de alguna forma, un 'manual de
> usuario'
> 	4) la documentación debería desarrollarse de forma independiente al
> código. En teoría por personal no técnico. Esto podría reflejarse en un
> árbol SVN propio (p.e.
> http://dev.pypyme.org/svn/doc/user_manual/[charon|portia|umbriel|...])
> 	5) no hemos decidido el formato de la documentación. En su momento se
> discutió (e incluso votó) pero nadie parece haberse interesado por
> desarrollar este tema
> 	6) para integrar la documentación en el 'Centro de Control' habría que
> decidir dónde instalar la documentación (me refiero al equipo del
> usuario pyPYME), ver NOTA 1, y diseñar un proceso que lo integre en la
> estructura de menús del 'Centro de Control', ver NOTA 2.
> 
> NOTA 1: La elección del directorio donde instalar la documentación
> presenta un problema:
> 
> 	- por una parte, desde el punto de vista del usuario, ha de estar
> integrada dentro de la aplicación (debe localizarse dentro del árbol
> org.pypyme)
> 	- por otra parte, desde el punto de vista de desarrollo, no debe
> mezclarse con el código (no debe localizarse dentro del árbol
> org.pypyme)

No estoy deacuerdo en esta parte... porque no debe estar dentro del arbol?

> 
> Para superar esta dificultad podemos:
> 
> 	1) asumir que el proceso de instalación creará un directorio 'manual'
> justo debajo del directorio raíz del módulo que documenta y copiará ahí
> el fichero o ficheros que formen el manual de usuario
> 	2) para probar su funcionamiento diseñaremos un test que, para un
> módulo dado:
> 		a) creará el directorio 'manual'
> 		b) copiará el contenido del directorio
> [...]/trunk/doc/user_manual/[módulo]/ al directorio 'manual' creado en
> el punto a)
> 		c) lanzará el 'Centro de Control'
> 		d) al finalizar el test, vaciará y eliminará el directorio creado en
> el punto a)
> 
> NOTA 2: Propongo añadir un submenú 'Ayuda', de primer nivel (fijo, parte
> del diseño del menú del formulario 'Centro de Control' al igual que el
> submenú 'Fichero'):

correcto...

> 
> 	Fichero | [módulos: Charon|Portia|...] | Ayuda
> 
> y dentro del menú Ayuda:
> 
> 	Manuales
> 		Datos Generales
> 		Ficheros Maestros
> 		Tesorería
> 		...
> 	-
> 	Acerca de...

de acuerdo.

> 
> donde la composición del menú 'Manuales' (inicialmente vacía) se
> realizaría dinámicamente, analizando los ficheros 'deploy.py' de los
> módulos. Para ello podríamos utilizar una nueva entrada que especificase
> la información necesaria:
> 
> 	manual = {
> 		'title'   : 'Tesorería',  # título a mostrar en el menú
> 		'path'    : 'manual',     # relativo al directorio raíz del módulo
> 		'filename': 'index.html', # o manual.pdf o el que sea
> 	}
> 
> ¿Qué os parece esta propuesta?
> 
> Saludos,
> Jose
> 
>