Documentación: El nuevo framework explicado
Documentación: El nuevo marco explicado
El nuevo módulo de documentación aspira a ser un buen compañero para usuarios, desarrolladores, redactores de documentación y traductores. Así que veamos los diferentes aspectos del marco.
Aspecto
En primer lugar, voy a mostrar el aspecto de la documentación dentro de Koo y lo que es posible hacer con ella. Como ya mencioné, esperamos que los clientes Web y GTK se sumen al esfuerzo, por lo que lo que ya tenemos en Koo debería estar disponible en esos clientes también.
Empecemos por lo simple. Hemos creado tres opciones de submenú dentro de Ayuda/Documentación.
La primera abrirá la documentación en una nueva pestaña de la aplicación:
La segunda abrirá la documentación en un archivo PDF que luego se puede imprimir. El contenido en ambos casos es exactamente el mismo.
La última entrada abrirá doc.openerp.com en una nueva pestaña de la aplicación. Pulse la tecla Control si desea que se abra en el navegador predeterminado de su sistema.
Como puede ver, en la primera y la última opción, los botones anterior y siguiente, así como el de recarga, de la interfaz estándar se utilizan como los botones habituales del navegador. De hecho, las acciones de URL ahora se abren dentro de Koo de forma predeterminada, excepto si el usuario pulsa la tecla Control como ya se mencionó.
Nota: Aunque la documentación normalmente será HTML, no es necesario abrir ningún puerto nuevo en OpenERP porque Koo utilizará su protocolo favorito (XML-RPC, Net-RPC o Pyro) para cargar HTML e imágenes a través de un nuevo protocolo interno:
openerp://.
Incluso si lo que hemos visto en la primera opción es lo que todos estamos acostumbrados a ver al abrir un manual, apenas es útil. Si quisiéramos leer el manual completo, podríamos imprimir su versión en PDF, pero eso es todo. De hecho, lo más habitual es que busquemos información en él, como un campo o una entrada de menú.
Con el nuevo marco, los usuarios casi siempre abrirán el manual utilizando la nueva interfaz contextual. La idea es que los usuarios puedan ver las partes del manual que se refieren al trabajo que están realizando en ese momento.
Esto tiene la ventaja de que los redactores de documentación escribirán un solo libro, con información estructurada como un libro, que se pueda leer de principio a fin. Al mismo tiempo, se garantiza que la documentación siga siendo útil porque los usuarios serán dirigidos a las secciones que necesitan cuando las necesitan.
La interfaz contextual está disponible actualmente en un par de lugares.
El primer lugar que los usuarios notarán es el nuevo botón Ayuda añadido a la barra de estado. Este proporcionará ayuda para las entradas de menú:
Aquí, los usuarios pueden ver los párrafos de la documentación donde se hace referencia al menú.
También proporciona ayuda para las vistas:
Aquí, los usuarios pueden ver los lugares que contienen capturas de pantalla de la vista. En ambos casos, los usuarios pueden hacer clic y ver la sección correspondiente en la documentación:
El segundo lugar en el que hemos añadido información contextual es en los campos.
Hasta ahora, solo los campos con una ayuda tenían un signo de interrogación. Ahora hemos añadido el signo de interrogación a todos los campos. Los que tienen una ayuda se muestran en azul y los que no, en negro.
Al hacer clic en el signo de interrogación se muestra no solo la ayuda, sino también todos los lugares de la documentación donde se menciona el campo:
Eso es todo lo que hemos implementado por ahora.
Otra característica que nos gustaría introducir es la capacidad de ver los lugares donde se menciona el estado actual del flujo de trabajo del documento actual. Esto permitiría a los usuarios entender completamente qué significa factura abierta, por ejemplo.
Aunque todo esto está orientado al usuario, también creemos que el marco debería utilizarse para incluir información para desarrolladores. Los integradores también podrían añadir todas las notas y documentación generadas durante el proceso de integración para un cliente determinado.
La documentación solo mostrará información relevante para los módulos que están instalados actualmente. Las capturas de pantalla también reflejarán lo que el usuario puede ver realmente.
Por ejemplo, si el usuario pertenece a un grupo que no puede ver ciertos campos, esos campos no aparecerán en sus capturas de pantalla, incluso si aparecen para otros usuarios.
Redacción
Estructura
Cada módulo nuevo puede tener —y esperamos que podamos convertir esto en un requisito— un directorio doc. La documentación se escribe utilizando sintaxis de Sphinx más algunas extensiones, por lo que Sphinx debe estar instalado en el servidor.
Esto asegura que la documentación permanezca cerca del código y que los desarrolladores se sientan cómodos con ella, al mismo tiempo que es inteligible para los redactores de documentación.
Se espera que el directorio doc contenga uno o más archivos .rst.
Alternativamente, si el módulo proporciona documentación para otros módulos, puede tener un subdirectorio modules que contenga la documentación para cada módulo que cubre.
No se preocupe si necesita leer esa frase dos veces; se me ocurrió y la escribí ;-).
Por ejemplo, como nosotros en NaN no tenemos acceso de confirmación al repositorio de addons, hemos creado algo de documentación para los módulos base, product y account.
Si el módulo se llama addons_doc, el directorio se verá así:
text
addons_doc/doc/
addons_doc/doc/modules/
addons_doc/doc/modules/base/
addons_doc/doc/modules/product/
addons_doc/doc/modules/account/
Si un módulo proporciona documentación para otros módulos y, por lo tanto, tiene un directorio doc/modules/, cualquier otro archivo directamente dentro de doc/ será ignorado.
Si quisiéramos proporcionar documentación para el propio módulo addons_doc, añadiríamos un nuevo directorio para él dentro de addons_doc/doc/modules.
Mencioné que la sintaxis de estos archivos es Sphinx más algunas extensiones. Hay dos tipos de etiquetas de extensión:
- Sustituciones
- Identificadores
Sustituciones
Las sustituciones permiten que cierta información en la documentación se complete utilizando el contenido de la base de datos que el usuario está ejecutando.
Actualmente, se implementan los siguientes tres tipos de sustitución.
Campos
Utilice la siguiente sintaxis:
text
/// f: res.partner.name ///
Reemplazará la etiqueta con la etiqueta del campo —Nombre en este ejemplo, cuando el idioma de salida sea inglés.
La referencia del campo se compone del modelo y el nombre del campo, separados por un punto.
También puede imprimir el texto de ayuda del campo utilizando la siguiente sintaxis:
text
/// f: res.partner.name : help ///
En ambos casos, el sistema creará un ancla inmediatamente antes del párrafo actual, lo que permitirá encontrar esta aparición del campo en el HTML generado.
Menús
Utilice la siguiente sintaxis:
text
/// m: base.menu_ir_sequence_form ///
Reemplazará la etiqueta con el nombre completo del menú:
text
Administración/Configuración/Secuencias/Secuencia
La referencia del menú utiliza la sintaxis modelo-datos que la mayoría de los desarrolladores están acostumbrados a usar en los archivos XML de vistas.
Este valor es fácil de obtener en Koo:
- Seleccione la entrada de menú.
- Haga clic en Cambiar vista.
- Haga clic en Complementos/Buscar datos del modelo en el menú superior.
El sistema también creará un ancla inmediatamente antes del párrafo actual.
En el futuro, haremos posible abrir la entrada de menú directamente desde la documentación.
Vistas
Utilice la siguiente sintaxis:
text
/// v: base.sequence_view ///
Reemplazará la etiqueta con una captura de pantalla de la vista. En este caso, generaría la siguiente imagen:
Al igual que con los menús, la referencia sigue la sintaxis modelo-datos.
También puede añadir un modificador:
text
/// v: base.sequence_view : fiscal_ids ///
Cuando el sistema genere la captura de pantalla, se asegurará de que el campo fiscal_ids se muestre, incluso si no está en la primera pestaña.
En este ejemplo, la imagen generada se vería así:
Esto es útil porque no sabemos cuántas pestañas habrá cuando se renderice la documentación. El campo que se está discutiendo también puede haber sido movido a otro lugar.
Esta característica no impide que los redactores de documentación añadan otras capturas de pantalla o imágenes. Deben añadirlas de la misma manera que lo harían normalmente con Sphinx, y se renderizarán correctamente.
El sistema también se asegurará de que los nombres de archivo no colisionen, por lo que los usuarios no necesitan preocuparse por eso.
Ejemplo
Con estas explicaciones, ya podemos entender un ejemplo simple que podría servir como parte de la documentación del módulo base.
El archivo index.rst:
```rst Manual de OpenERP ==================
Contenido:
.. toctree:: :maxdepth: 2 :numbered:
base.rst ```
Como puede ver, index.rst le dice a Sphinx que cargue el archivo base.rst, que podría verse así:
```rst Configuración =============
Secuencias
En /// m: base.menu_ir_sequence_form /// puede gestionar las secuencias que permiten a usuarios avanzados determinar cómo se generarán los números de documento.
/// v: base.sequence_view /// ```
Identificadores
Los identificadores siguen esta sintaxis:
```text ||| nombre_del_identificador_que_quiero |||
Aquí comienza el párrafo al que queremos asignar este identificador. ```
Deben aparecer al inicio de un párrafo. El párrafo en sí debe comenzar en la siguiente línea o en la siguiente línea no vacía.
Las etiquetas de identificador permiten asignar un ID a cada párrafo, similar a lo que hacen los desarrolladores con las vistas, aunque los identificadores no son obligatorios.
Si los redactores de documentación no proporcionan un identificador para un párrafo, el sistema creará uno automáticamente.
Para crearlo, el sistema utilizará las primeras palabras del párrafo y añadirá un número si es necesario para asegurar que el ID sea único dentro de su módulo.
Los identificadores también pueden seguir esta sintaxis:
```text ||| : after : base.base_rst |||
product.rst ```
En este caso, el identificador para el párrafo se creará automáticamente.
Alternativamente, puede proporcionar un identificador explícitamente:
```text ||| add_product_rst : after : base.base_rst |||
product.rst ```
En ambos casos, estamos indicando al sistema que añada el párrafo —que en este caso simplemente contiene product.rst— inmediatamente después del párrafo con el identificador base.base_rst.
Esto se refiere al párrafo con el ID base_rst en el módulo base.
Mirando el ejemplo anterior, notará que estamos añadiendo un nuevo archivo product.rst al archivo index.rst creado por el módulo base. Como habrá adivinado, esta documentación formaría parte del módulo product.
La sección de ubicación de la etiqueta de identificador puede usar actualmente cualquiera de los siguientes valores:
beforeafterprependappendreplace
Las opciones before y after crean nuevos párrafos y, por lo tanto, añaden una línea vacía entre el nuevo párrafo y el heredado.
Las opciones prepend y append no crean nuevos párrafos.
Este mecanismo de herencia proporciona una gran flexibilidad y ayuda a evitar el problema del if condicional mencionado en mi publicación de blog anterior.
Sin embargo, debido a que los párrafos se utilizan como referencias, los redactores de documentación deben tener esto en cuenta al estructurar el contenido.
Por ejemplo, en Sphinx, una lista de definiciones se puede escribir así:
rst
palabra1
explicación 1
palabra2
explicación 2
O así:
```rst palabra1 explicación 1
palabra2 explicación 2 ```
Ambas versiones son válidas en Sphinx y en este marco.
Sin embargo, la segunda proporciona más flexibilidad si alguien crea un nuevo módulo y necesita añadir una nueva entrada entre palabra1 y palabra2.
Los identificadores creados automáticamente pueden cambiar con el tiempo si no se establecen manualmente, porque las primeras palabras de un párrafo pueden ser editadas.
Por esta razón, planeamos permitir que el sistema almacene los IDs generados automáticamente en los archivos .rst originales.
Esto permitirá a los redactores de documentación corregir libremente errores tipográficos o reestructurar oraciones sin romper la documentación perteneciente a módulos dependientes. También eliminará la necesidad de crear manualmente un ID único para cada párrafo.
Aparte de conocer un poco de Sphinx, esto es todo lo que necesita saber para escribir documentación para este marco.
Funcionamiento
En la sección anterior, explicamos que la documentación residirá dentro de los módulos, muy cerca del código fuente.
Aquí, explicaremos lo que hace el sistema y los pasos necesarios para importar y renderizar la documentación.
Después de instalar el módulo documentation en OpenERP, aparecerá una nueva entrada Documentación en el menú principal.
Lo primero que debe hacer es ejecutar el Asistente de importación de documentación.
Este asistente verifica el directorio doc/ de cada módulo e importa los archivos .rst en la base de datos de OpenERP párrafo por párrafo.
Como se mencionó anteriormente, el sistema considera que un párrafo termina y uno nuevo comienza después de cada línea vacía.
Una vez que los párrafos han sido importados, puede verlos en la entrada de menú Párrafos de documentación.
A continuación, deberá:
- Abrir Párrafos de documentación.
- Seleccionar todos los párrafos.
- Ejecutar la acción Complementos/Crear capturas de pantalla en el menú superior.
No hace falta explicar qué hace esta acción, supongo.
Finalmente, ejecute el Asistente de generación de documentación. La documentación estará entonces lista para usar.
Traducción
El asistente de importación añadirá un registro a ir.data.model por cada párrafo.
Esto significa que cuando cree un archivo de plantilla de traducción .pot para un módulo, la documentación también se exportará.
Fácil.
El proceso de traducción también se simplifica porque el redactor original ya ha utilizado etiquetas para referirse a menús y campos.
Como resultado, los traductores no tienen que determinar los nombres exactos asignados a estos elementos en su idioma.
Lo mismo se aplica a las capturas de pantalla, ya que se generarán automáticamente en el idioma del usuario para cada instalación.
El futuro
Ya hemos mencionado algunas de las mejoras que nos gustaría hacer, como las referencias a flujos de trabajo y sus actividades o la capacidad de abrir entradas de menú desde la propia documentación.
Otras ideas incluyen:
- Evitar obligar a los usuarios a abrir la sección de Párrafos y seleccionar todos los párrafos antes de crear capturas de pantalla.
- Regenerar la documentación cada vez que sea necesario sin que el usuario lo note o lo solicite.
- Integrar la importación de documentación con la instalación de módulos para que no sea necesario un proceso de importación separado.
- Permitir a los usuarios añadir sus propias notas dentro de la documentación, ya que tienden a usar su propia terminología y seguir sus propios procesos.
- Añadir un apéndice con información técnica sobre los módulos instalados en el sistema.
