Enlaces a partes anteriores:
- Primera parte : introducción, primitivas gráficas necesarias para crear una representación gráfica del código
- Segunda parte : implementación de una representación gráfica del generador de código (hecho principalmente en Python), lenguaje de micro marcado
- Tercera parte : nuevas características gráficas
Un ejemplo de un entorno que admite esta representación gráfica se muestra en la imagen a continuación.
Entorno de soporte de código gráficoLa cuarta parte del artículo se centrará en apoyar el proceso de documentación.
Alrededor del arbusto
Veamos qué hay disponible para el desarrollador en términos de trabajar con la documentación.
Python admite líneas de documentación para módulos, clases y funciones. Esto es bueno Los comentarios también se utilizan a veces para la documentación.
Hay generadores de documentación como
doxygen y
sphinx . Esto también es bueno.
Sin embargo, a veces quieres un poco más. Hay momentos en que la descripción de una función o clase es demasiado grande y las líneas de documentación (o comentarios) se "hinchan" innecesariamente. El número de líneas no ejecutables comienza a suprimir el número de líneas ejecutables, lo que puede dificultar la lectura debido al código borroso. Otro problema son los diversos gráficos. No puede insertar una imagen terminada en el texto. Solo puede insertar una descripción del diagrama, por ejemplo, un
diagrama Plant UML , pero incluso en este caso es necesario proporcionar renderizado, que es difícil de hacer directamente en el texto del programa.
La solución al problema es simple: guardar una descripción larga en un archivo separado y dejar una nota en el código que indique que la documentación está allí. Un solo archivo se puede representar adecuadamente en el momento adecuado. Y la marca en el código preferiblemente debe ser interactiva, es decir, proporcionar una transición a la documentación con un solo clic del mouse. En principio, la marca en el texto del programa puede considerarse de manera más amplia: puede ser una URL, y algún lugar en otro archivo del texto fuente, y una imagen, y un archivo externo con documentación.
Es fácil imaginar un vínculo de retroceso. Digamos que la documentación menciona una clase del código fuente de un programa o incluso un bloque de código específico. Para este caso, también sería bueno proporcionar una transición rápida al código deseado.
Necesitamos considerar otro escenario importante. Supongamos que durante el desarrollo hubo un deseo de crear un archivo de documentación externo. Es altamente deseable que la cuestión organizativa: dónde almacenar, cómo llamar, cómo poner un enlace a la documentación, se resuelva de la manera más automática posible para que no haya una barrera innecesaria que pueda sofocar el impulso justo de crear documentación.
Una discusión separada merece la cuestión del formato de los archivos de documentación. Recientemente, la
rebaja ha ganado
popularidad , a pesar de las críticas (por ejemplo,
aquí ). Digamos que github muestra automáticamente la documentación de rebajas cuando ingresas a la página del proyecto, lo cual es bastante conveniente. En este caso, debe seguir un acuerdo muy simple e intuitivo sobre el nombre y la ubicación del archivo. Las herramientas para trabajar con Markdown también son abundantes, por lo que este formato es un buen candidato.
Implementación en el IDE de Codimension
Junto con el texto, el
IDE de Codimension admite la representación gráfica del código. El IDE también admite lenguaje de marcado. Por lo tanto, la tarea de agregar un nuevo elemento gráfico para mostrar enlaces a la documentación es bastante simple.
Para comenzar, formulamos los requisitos para la nueva funcionalidad en una forma compacta:
- Admite formato de rebajas con renderizado sobre la marcha (ver y editar)
- En la representación gráfica del código, admite un nuevo elemento para la documentación utilizando el lenguaje de marcado CML
- El elemento gráfico para la documentación debería funcionar en tres versiones: solo un enlace a otro lugar; solo ancla para enlaces de otros lugares; y enlace y ancla
- El enlace puede ser una URL o apuntar a un archivo (posiblemente con una línea o un número de ancla) que el IDE puede mostrar
- En Markdown Support Diagramas de planta UML
- Admite la creación rápida de nuevos archivos de documentación y enlaces a ellos para la presentación gráfica de código
- Mantener el punto de partida de documentación de documentación para un proyecto, similar a cómo lo hace github
Markdown y renderizado
Codimension IDE usa
qutepart como componente del editor de texto, y qutepart, a su vez, admite el marcado de fábrica: el resaltado de sintaxis ya se ha realizado. Para la representación automática, puede usar el mismo enfoque que para los archivos de Python. El campo principal se divide en dos partes. A la izquierda está el texto de marcado, y a la derecha está renderizando:
Edición de rebajas con renderizado automáticoLa representación, por supuesto, se realiza automáticamente. El IDE define una pausa en la edición de texto y actualiza la representación si es necesario. Para la vista de reducción, se suprime el lado izquierdo con un editor de texto.
Era conveniente usar la biblioteca de
mistune para
renderizar , lo que le permite convertir rápidamente texto a HTML. El HTML listo se envía al componente QT para su visualización. La biblioteca de mistune también demostró ser lo suficientemente flexible como para agregar reconocimiento a las descripciones del diagrama plantUML. El diagrama se agrega como un bloque de código con el idioma correspondiente, por ejemplo:
Reconocimiento de diagrama PlantUMLplantUML admite varios tipos de diagramas. Para
Codimension, la descripción del diagrama es transparente, es decir, no se analiza, pero plantUML se transmite tal como está. En consecuencia, todos los tipos compatibles se mostrarán en la ventana gráfica. En el momento de la redacción, plantUML admite las siguientes etiquetas de inicio / finalización para varios tipos de diagramas:
- @startuml / @enduml
- @startgantt / @endgantt
- @startsalt / @endsalt
- @startmindmap / @endmindmap
- @startwbs / @endwbs
- @startditaa / @endditaa
- @startjcckit / @endjcckit
El archivo de reducción editable puede contener varios diagramas, así como imágenes descargadas de la red. Una situación frecuente es cuando cambia muy poco texto y los recursos gráficos permanecen sin cambios. Para no bombear lo mismo cada vez y no regenerar diagramas, fue necesario implementar un caché de recursos similares.
Desde la biblioteca QT, se utiliza el componente QTextBrowser que admite HTML. Desafortunadamente, el dialecto compatible de HTML es limitado, por lo que el resultado final es casi imposible de perfeccionar. Quizás este defecto se pueda solucionar en el futuro.
También se requirió intervención mediante el procesamiento de los clics del mouse en los enlaces. Algunos de los siguientes pueden aparecer en el enlace:
- recurso externo (comienza con http: // o con https: //)
- un archivo con una ruta relativa desde la raíz del proyecto o desde el archivo actual (conveniente cuando el directorio del proyecto se mueve alrededor del sistema de archivos)
- ruta absoluta del archivo c
Y si se trata de un archivo, puede especificar (elemento opcional) el identificador del ancla en este archivo o el número de línea. En ambos casos, se utiliza información adicional para desplazar el archivo a la ubicación deseada.
Elemento gráfico
Tiene sentido ingresar un elemento gráfico usando un nuevo comentario CML, similar a como ya se ha hecho, por ejemplo, para grupos. CML admite atributos, que también se requieren para el nuevo elemento gráfico.
Un enlace a la documentación es de alguna manera similar a un comentario: no es una línea ejecutable del programa, pero proporciona información adicional sobre algún contexto.
El IDE de Codimension reconoce varios tipos de comentarios: independientes,
iniciales y laterales. Para la documentación, parece prudente mantener elementos gráficos independientes y líderes de la misma manera que para los comentarios. Hay confusión con el elemento lateral para la documentación. El punto es cómo se representan los comentarios laterales para un bloque de código de varias líneas. Se dibuja un rectángulo a la derecha del bloque, que cubre todas las líneas del comentario lateral con soporte para hacer coincidir los números de línea. Y qué hacer si el documento CML se reunió en el medio del comentario lateral no está del todo claro. Por otro lado, el enlace todavía conduce a otro lugar, por lo que el soporte para documentos CML secundarios parece redundante: el contexto de una línea particular en el bloque de código es muy estrecho. La compatibilidad con documentos CML secundarios para funciones y clases también parece redundante. Por lo tanto, en esta etapa solo se implementarán documentos CML independientes y líderes. Vale la pena señalar que si en el futuro existe una necesidad razonable de admitir documentos CML laterales y una buena idea de cómo mostrarlos, entonces se puede agregar esta funcionalidad.
Analicemos lo que debe mostrarse en un elemento gráfico. Obviamente, necesita texto para el elemento. El desarrollador establece el texto y le indica a qué apunta el enlace. Se mencionó anteriormente que es deseable proporcionar una transición a la documentación con un solo clic. El texto del elemento gráfico no es adecuado porque se debe respetar la continuidad entre el comportamiento de otros elementos: al hacer clic con el mouse, se selecciona el elemento gráfico. Sin embargo, resolver el problema es simple: puede agregar un icono, por ejemplo, a la izquierda del texto, y hacer clic en el icono conducirá a la transición.
Ahora la lista de atributos para el comentario del documento CML es clara:
- enlace - enlace a otro lugar
- ancla: identificador de anclaje para enlaces desde otros lugares
- título - texto para mostrar en el elemento gráfico
- bg, fg, border: colores individuales del elemento, si es necesario resaltarlo de manera especial
Al menos uno de los dos atributos link y anchor debe estar presente. Sin ellos, tal comentario de documento de CML no tiene mucho sentido. Otros atributos son opcionales. El texto puede no ser del todo, y los colores pueden ser estándar.
Aquí hay un ejemplo de código que usa el documento CML y su representación gráfica:
Comentarios independientes y destacados sobre documentos de CMLLa diferencia entre elementos principales e independientes es solo donde el conector conduce: ya sea a un bloque específico o a un conector entre bloques.
Cuando el cursor del mouse está sobre el icono y el elemento tiene un atributo de enlace, la forma del cursor cambia, lo que sugiere que se realizará un clic.
El elemento gráfico también es compatible con el menú contextual. Hay una opción disponible para ver o editar atributos de elementos, incluidos los colores, y la opción de eliminar un elemento.
Otros elementos gráficos
Casi todos los demás elementos en la representación gráfica del código pueden tener documentación (las excepciones, por ejemplo, son comentarios y cadenas de documentos). Por lo tanto, tienen una manera de crear un elemento de documentación a través del menú contextual.
Menú contextual para trabajar con documentaciónSolo hay dos opciones. El primer "Agregar / editar enlace / ancla de documento ..." lleva a un cuadro de diálogo modal para ingresar manualmente los atributos de enlace, ancla y título. Aquí, el desarrollador tiene total libertad para enviar el enlace, dónde colocar el archivo, etc.
La segunda opción es más interesante. El nombre del elemento es largo, debido a las acciones realizadas: "Crear archivo de documento, agregar enlace y abrir para editar". Todas las acciones se realizan automáticamente sin ninguna entrada, lo que le permite resolver el problema de la organización rápidamente:
- Se toma una decisión sobre el archivo en el que se ubicará la documentación (lo consideraremos a continuación)
- En el texto fuente, agregue
# cml 1 doc ... , que apunta al archivo de documentación y tiene el ancla y el texto generados. El ancla se genera como doc <número aleatorio>. Texto fijo: ver documentación - Si el archivo de documentación ya existe, se abre para editarlo en una nueva pestaña
- Si el archivo de documentación no existe, se crea, se abre para editarlo en una nueva pestaña, y se agrega una breve ayuda al búfer de edición, que incluye cómo consultar el comentario
# cml 1 doc ... insertado.
La decisión sobre el archivo depende de si el proyecto está cargado. Si está cargado, se crea el subdirectorio doc en la raíz del proyecto y luego la ruta relativa desde la raíz del proyecto hasta el archivo de texto fuente. El nombre del archivo se forma reemplazando la extensión con .md. Por ejemplo, si un proyecto se encuentra en
/home/me/myProject
y se agrega documentación para el archivo del proyecto
/home/me/myProject/src/utils.py
se creará un archivo de documentación
/home/me/myProject/doc/src/utils.md
Por lo tanto, la estructura de la documentación para el código fuente repite la estructura del código fuente, e incluso un vistazo rápido al subdirectorio doc en el proyecto será suficiente para una navegación intuitiva. El esquema parece razonable para el comportamiento predeterminado, lo que ayuda a acelerar el trabajo con la documentación.
Si el proyecto no se carga, se crea el subdirectorio doc junto al archivo y en él el archivo con la extensión modificada a .md. Tal escenario, sin embargo, parece poco probable. Si hablamos de documentación, es casi seguro un trabajo en un proyecto, y no en un archivo separado.
Por supuesto, en cualquier momento puede cambiar los elementos generados automáticamente editando
# cml 1 doc ... en un editor de texto o en un cuadro de diálogo en una representación gráfica.
Documentación del proyecto punto de partida
¿Por qué necesito un punto de partida de documentación? En mi opinión, puede facilitar el proceso de ingreso al proyecto para quienes lo abren por primera vez. Por ejemplo, en el caso de ampliar la composición del equipo de desarrollo, o para los usuarios del proyecto. Imagine que el proyecto tiene documentación y consta de una gran cantidad de archivos. Por donde empezar ¿Cómo se estructura la documentación? En lugar de especular y luego verificarlos, sería más conveniente tener una indicación explícita del punto de entrada recomendado.
Aquí puede ampliar un poco el enfoque de github para que funcionen las opciones de organización de documentación predeterminadas y específicas. Si no se dice nada, buscaremos el archivo README.md en la raíz del proyecto. Y las propiedades del proyecto se pueden ampliar con otro campo, que indica un archivo específico del punto de partida de la documentación.
Hay dos opciones para abrir la documentación del proyecto. Se ha agregado un botón con el icono de reducción a la barra de herramientas de la ventana principal de IDE. Al hacer clic, el archivo de documentación se abrirá en modo de visualización, si está disponible. Si no hay ningún archivo, se ofrecerá la ubicación del archivo de documentación y se abrirá una nueva pestaña en modo de edición con el texto: un trozo. La segunda opción es un enlace a la página de bienvenida de
Codimension , que se muestra cuando no hay otra pestaña abierta. El texto adjunto incluirá palabras sobre la documentación del proyecto y un enlace si se encuentra la documentación. Es esta página de bienvenida la que verá el usuario que abrió el proyecto por primera vez.
Pruebas en práctica
La funcionalidad descrita anteriormente se probó en gatos, es decir, en el proyecto del
propio IDE de Codimension . Ahora el paquete de instalación incluye documentación preparada en formato de descuento. Esta prueba de funcionalidad no puede considerarse completamente completa, ya que la documentación fue preparada para el usuario final, y no por código. Sin embargo, la impresión general de que resultó es bastante aceptable.
Preguntas abiertas
¿Necesito soporte para elementos de documento CML laterales? En caso afirmativo, cómo dibujarlos, por ejemplo, para tal caso:
a = 10
Uno podría reconocer las descripciones del diagrama plantUML directamente en las líneas de documentación. Si se realiza dicho soporte, ¿cómo mostrar estos diagramas en la representación gráfica del código?
Para facilitar la construcción de diagramas plantUML, se podría agregar funcionalidad con este escenario:
- El usuario hace clic con el botón derecho en la clase en la representación gráfica del código o en cualquier otra ventana (lista de clases de proyecto, contenido del archivo estructurado)
- En el menú contextual, selecciona un elemento para generar una descripción de clase en formato plantUML
- La descripción generada se guarda en un búfer de texto.
- El usuario inserta texto en el documento de descuento y lo modifica si es necesario
La vitalidad de tal escenario está en duda, aunque es trivial implementarlo.
Si tiene alguna idea, compártala en los comentarios.