Símbolos exportados por cáda módulo en PixTudio

[darío]

Hola,

He estado trasteando con PixTudio (descargado con Git y compilado en Fedora 23)... Me encanta la idea de un derivado de BennuGD con gran atención a las plataformas móviles.
Como aficionado a "crear herramientas" en lugar de "crear juegos" y con algún íncipit de proyecto que empieza a tomar forma me han surgido una duda:

Es posible, de un modo automatizado a partir de los binarios compilados o de los sources extraer una lista de todas las funciones de los módulos? Por ejemplo, cómo hacéis para generar la documentación de la página de la documentación? BennuGD disponía de una herramienta (moddesc) que permitía saber los símbolos que se exportaban de cada módulo. Es posible algo parecido? Es posible extraer la información de los tipos o el nombre de los parámetros?

La única forma que se me ocurre por ahora es parsear la información contenida en los mod_modulanme_symbols.h... pero digo yo que la documentación de PixTudio no la generáis a mano, no?

Tenéis alguna sugerencia?

Gracias de antemano,
Darío

[josebita]

Gracias por el interés.

De momento la documentación que aparece en la web de PixTudio no es más que la de la Wiki de Bennu cambiada un poco de formato (pero verás que aún hay muchas secciones que tienen el formato roto o incorrecto).
No hay nada automático porque todavía no le he dado mucho cariño a la documentación. Toda ayuda en ese sentido es bienvenida.

[darío]

Hola,

Gracias por la respuesta.

La verdad es que si quiero ayudar, no tanto con la documentación sino con otra cosa... Siempre he pensado que los DivLike han sufrido mucho de carencia de IDEs, sobretodo en entornos no-windows. En lugar de intentar reinventar la rueda he estado estudiando MonoDevelop y estoy viendo que es relativamente sencillo crear Addins y creo que sería un estupendo IDE multiplataforma para PixTudio (y posiblemente para Bennu) así que he iniciado un proyecto llamado PixTudio Develop. Mirar la imagen en el attachment para haceros una idea de los progresos (sintax highlighting y templates).

Creo que MonoDevelop es una plataforma especialmente interesante como IDE para PixTudio no solo porque sea fácil extenderlo sino por su obvia connexión a Xamarin y por tanto el interés que puede existir en desarrollar applicaciones (en este caso juegos) para iOS y Android desde un entorno en el que seguramente muchos están habituados. Además, los addins para MonoDevelop son compatibles con Xamarín, y puesto que Xamarín no funciona en Linux, es posible que PixTudio pueda atraer la atención de aquellos que quieran desarrollar juegos multiplataforma :).

Mi pregunta anterior se basa en el hecho que obviamente me gustaría poder dotar de tooltips y autocompletion a PixTudio Develop como en su día tenía Flamebird, así como poner facilidades para estudiar las funciones que están contenidas en cada módulo... Por tu respuesta entiendo que la forma más fácil es probablemente extrayendolo a partir del código fuente de PixTudio... A ver qué puedo hacer.

Darío

P.D.: Si tenéis algún problema con el nombre del proyecto hacedmelo saber y se lo cambiaré, pero vamos el Addin será open source como es de esperar...

[josebita]

Me parece una idea extraordinaria y estoy de acuerdo en que hacen falta IDEs y, sobre todo, fuera de Windows.
Ánimo con el proyecto :)

Voy a dedicarle un poco de cariño a la documentación, a ver hasta dónde llego.

[darío]

Hola Josebita,

Al final leyendo un poco los sources de PixTudio se me ha ocurrido que en realidad sí puedo ayudar... Creo que puedo automatizar la generación de la documentación y he hecho una prueba que me parece satisfactoria, a ver qué opináis.

La idea es, desde los archivos _symbols.h de la carpeta modules originar una serie de archivos en MarkDown y luego con algún generador de documentación (yo he probado mkdocs con resultados bastante convincentes) original unos html estáticos (por lo que se evitan problemas de seguridad).

He subido el resultado aquí: http://dacucar.com/pixtudiodocs/

De esta forma, la documentación siempre listará al menos todos los símbolos exportados (lógicamente habría que fusionar los "lib.." con los "mod...").

Ahora, para rellenar el contenido tengo algunas ideas iniciales:

- Un repositorio de ejemplos, donde sólo hay código PixTUdio. El generador de documentación inspeccionará estos archivos en busca de las funciones y los incluirá como ejemplos en las funciones correspondientes.

- Un archivo con sintáxis md para cada símbolo (función, constante, etc.) donde se explica cada función (esto lógicamente toca hacerlo a mano, pero con la novedad de que al ser archivos planos de texto es muy fácil editarlo al contrario que la wiki) y que el generador combinará con la información autogenerada. Y sí, intentaré reaprovechar la documentación de BennuGd en la manera de lo posible.

La idea es que sea tremendamente fácil documentar las funciones, poder tener control de cambios (git) pero al mismo tiempo ser consciente siempre de todas las disponibilidades del lenguage.

El generador (PixTudioDocGen) está disponible en https://bitbucket.org/dacucar/pixtudiodocgen/src pero ahora mismo está un poco guarrete y todavía no hay instrucciones sobre cómo usarlo.

Agradezco opiniones al respecto.

[josebita]

Muy interesante, Darío, muchas gracias.

La documentación que hay ahora mismo en https://pixtudio.org/docs está generada a partir de los MarkDowns de aquí:
https://bitbucket.org/josebagar/pixtudio/src/f525ffeb7f02f6cf6d204261bb9a092849813407/docs/web/docs/?at=bigmap
Como verás, en la carpeta "docs" del código fuente está toda la página web de pixtudio.org, incluídos los scripts PHP que convierten la documentación MarkDown->HTML. Los archivos markdown de la web se corresponden con una exportación de la Wiki (no tengo intención de mantener una Wiki para la documentación: ya hemos visto que eso es demasiado trabajo) con un pre-filtro para el formato, pero el formato aún no está bien y hay un montón de cosas que actualizar (incluídos cambios de nombre, me temo).

No sé si hay forma de compatibilizar ambos sistemas.

Lo que sí podré, al menos, es usar tu programa como guía de qué falta por documentar, que ya es bastante...

[darío]

Hola,


Sí había pensado reaprovechar eso en la medida de lo posible.


No obstante yo tengo una idea un poco diferente de cómo debiera ser un sistema de documentación flexible. El problema que le veo a que cada elemento del lenguaje (función, identificador, constante o variable) cuente con un archivo .Mk es que estos archivos contienen contenido y estilo, pero nada que "describa" la información que hay dentro.


Yo lo que he pensado es que cada elemento del lenguaje cuente con un archivo por ejemplo .YAML donde se describen la información necesaria. Por ejemplo para una constante podría ser:

Code Select Expand



name : _A
value : 65
brief : Keycode for A
seealso : mod_key
description:
    Una constance que hace esto y lo otro
    para blablabla. Parecido a lo que hace
    [_B] y [_C].

[/size]

El autogenerador de documentación generaría éstas plantillas para nuevos elementos cuando no existiesen o combinaría con los ya existentes. En una fase posterior, esta información se utilizaría para elaborar los archivos MarkDown, pero también sería reutilizable por ejemplo desde cualquier IDE.


Se distinguiría por tanto lo que es "documentar los símbolos y palabras claves" de lo que es "documentación literaria" (que se haría en archivos MarkDown).


En fin, de momento son unas cuantas ideas desordenadas y es mejor esperar a que muestre algo para hacerme comprender del todo...


Cuando avance la cosa, hago saber. Un saludo,


Darío

[josebita]

Pues te agradezco mucho que le andes dando vueltas, y me gusta la idea de que la documentación pueda ser aprovechada por los IDEs, pero la verdad es que desconozco cómo hacerlo. Te agradeceré esos ejemplos  :)

[panreyes]

Hola Darío,

¿Podrías darle a actualizar a tu script que exporta todos los nombres de funciones? :D

Un saludo!

[darío]

Claro, esta tarde lo hago.

[darío]

http://dacucar.com/pixtudiodocs

[josebita]

Cada vez me estoy inclinando más por utilizar tu opción, Dario, combinada con lo que hay ahora mismo.
¿Sería posible hacer que al pasar el lexer buscara la documentación para cada símbolo entre los archivos MD que ya están generados y los utilizara?

También sería de gran utilidad que imprimiera una lista de símbolos cuya documentación no ha podido encontrar.
Luego faltaría limpiar los archivos MD, que se han generado a partir de comandos de la wiki y muchos no son (aún) MarkDown de verdad y añadir documentación para los símbolos que no la tienen.

[Edito] Te he puesto un merge request con una tontería. A ver si lo he hecho bien...

[darío]

Hola,

No se si leíste el README que explicaba un poco a groso modo la intención del proyecto.

Las opciones que comentas las había pensado, solo que mi idea no sería mantener los MD sino aspirar a que la documentación se guardara en archivos YAML (que son estructurados pero legibles). Un concepto que estuve experimentando en la rama "yamlsources".

Ejemplo:

Code Select Expand


--- # mod_screen
brief: >
    Definition and manipulation of screen areas.

usage: |
    Write a text in mark-down that can explain what this is.

region_define:
    brief        :    >
                      Defines the boundaries of a [region]()
    explanation  :    |
                      There are 32 regions, range ```0..31``. Region
                      0 is always the whole screen and cannot be changed.
                      Defining regions can be useful for the function
                      [out_region](), the [local variable]() and using
                      with [scrolls]().
    parameters   :
                      - region_id:
                         description : unique identifier of the                       
                      - x
                      - y:
                         - description : the y-coordinate
                         - optional    : No
                      - width
                      - height
                     
    returns      :    the identifier of the region
   
region_out:
    brief        :    >
                      Checks if the specified [process]() is completely outside
                      the specified [region]()
    explanation  :    |
                      The check is not pixel perfect, but uses the [bounding box]()
                      of the graph of the process.
    parameters   :
                      - process_id : "the [process id]() of the process to check"
                      - region_id  : "the [region id]() of the region to check with"
    returns      :    >
                      [true]()/[false]() whether the process is completely outside the region
                     
                     
function_specification:
    brief        :    >
                      A one-line short-description of the purpose of the function.
                      Do not end it with a dot. Starts with capital letter
    explanation  :    |
                      Complementary information. Starts with capital letter, ends
                      with a dot.
    parameters   :
                      - parameter_1 : "parameter description start with lower-case"
                      - parameter_2 : >
                                      multiline parameter
                                      description. Do not end with a dot
                      - parameter_3 :
                          - description : explicit parameter description
                          - optional    : Yes
    returns      :    >
                      [true]()/[false]() whether the process is completely outside
                      the region
    see-also     :
        - "[reference-1]()"
        - "[reference-2]()"
       
    examples     :
        - mod_screen.pxt
       
...


Al ser archivos estructurados es muy fácil cargarlos y trabajar con ellos desde lenguajges de programación como Python. Esto posibilitaría lo que dices de detectar los símbolos que no se han podido documentar. Pero también detectar si los parámetros coinciden con la signature de las funciones y similar.

Al ser legibles, uno podría imaginar un repositorio donde todos pueden contribuir a documentar. Al poder guardarse como repositorio, la documentación podría estar ligada a las releases de pixtudio. Lo ideal en este caso creo sería un repositorio separado, que es incluido en pixtudio como un submodulo.

Con respecto a cómo utilizar la información de los MD que existen ahora consideré varias opciones:

- Hacer un parser de dicha información (no se si merece la pena)
- Copy&Paste uno por uno (un poco tedioso pero solo una vez...)
- Incluir la documentación MD tal cual en algun campo del archivo YAML creado a tal fín, de tal modo que la función quedase "temporalmente documentada" hasta que hubiera tiempo de adaptarla manualmente al mismo formato. Esto a su vez permitiría un "Copy&paste" gradual, donde varias personas podrían contribuir.

Aunque no escribo mucho, estoy bastante activo y estoy trabajando "en secreto" en un port simplificado de mi SmartFpgEditor a C# con Xwt ya que me gustaría tener una herramienta que tenga un "native look&feel". Pero puedo hacer un parón y darle otra vuelta de tuerca al PixTudioDocGen si piensas que lo que propongo puede ser un buen sistema.

Atenderé al pull-request en cuando pueda :) gracias.

Un saludo,

Darío

[josebita]

Lo ví, sí.
Igual me monto alguna herramientilla para poder hacerlo, porque es muy doloroso (aunque necesario).