Tenemos algunas interfaces basadas en XML que están bastante bien documentadas en los esquemas XSD. Las interfaces ahora estarán disponibles públicamente y nos gustaría crear documentación de referencia para ellas.¿Cómo convertir xsd a documentación legible para humanos?
¿Hay alguna herramienta que pueda convertir automáticamente archivos XSD en un formato más legible?
No debe ser difícil convertirlo (o escribir con anticipación) al formato docbook.
Una secuencia de comandos XSLT puede hacer el trabajo.
oXygen tiene muy buena XSD schema documentation tool que permite una fácil personalización a través de opciones y archivos CSS adicionales.
No lo he usado antes, pero DocFlex/XML es una herramienta de documentación XML con un componente de documentación XSD llamado XSD Doc que parece interesante.
Como se señaló en otras respuestas, XSD es solo un archivo XML, por lo que se podría escribir un XSLT personalizado para generar cualquier salida de documentación que desee.
Las probabilidades son bastante buenas de que no desee utilizar una herramienta genérica para documentar su esquema. Las herramientas de documentación de esquemas (estoy muy familiarizado con el de XML Spy) están diseñadas para hacer que los esquemas sean legibles. Según tu descripción, parece que eso no es realmente lo que quieres; lo que desea es usar la información en su esquema como la base de la documentación del software.
Cuando tuve que hacer esto, el enfoque que tomé fue diseñar HTML que se veía como necesitaba la documentación para buscar, y luego averiguar qué información en el esquema necesitaría obtener para rellenarla . Usando eso como plantilla, es bastante sencillo extraer información relevante del esquema usando XSLT.
He generado documentación en el pasado usando una herramienta que encontré en Freshmeat.net llamada xsddoc. Buscándolo ahora (para obtener el enlace directo), veo que ha sido reemplazado por sus desarrolladores con una herramienta llamada xnsdoc. La más nueva es gratuita para el uso de proyectos de código abierto, pero si está utilizando esto para un producto comercial, es posible que deba licenciarlo. Si la última versión publicada bajo el banner "xsddoc" se adapta a sus propósitos, entonces puede usarla.
los textos que elabore tiene la apariencia de Javadoc, y permite cierto grado de control en la hoja de estilo, etc.
x3sp puede hacer lo que quiera: http://xml.fiforms.org/xs3p/
Guau, sorprendido por los votos, tal vez porque hay muy pocas alternativas, pero el resultado de x3sp es increíblemente feo y difícil de seguir: solo leer el xsd simple es mucho más fácil. ¿Y qué pasa con el tipo "AusAddress" al azar al final? –
La página vinculada ya no parece existir, y no puedo encontrar rastros de un software llamado * x3sp * al menos con una búsqueda rápida en la web. –
Insertar esta en la parte superior de XSD
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="xs3p.xsl"?>
A continuación, puede ver directamente el archivo XSD utilizando un navegador web. El navegador web realiza la conversión a HTML utilizando el XSLT especificado.
no necesita necesita un procesador XSL, pero las hojas de estilo como xs3p no generarán enlaces utilizando este enfoque. Uso el navegador web Firefox, IE8 parece inútil para esto.
He probado estas hojas de estilo XSL: https://sourceforge.net/projects/xs3p/files/xs3p-1.1.3.zip/download http://crism.maden.org/consulting/pub/xsl/xsd2html.xsl
creo que prefiero xs3p.
Para aclarar: los navegadores web modernos (como Firefox) tienen un procesador XSLT incorporado que permite que se produzca esta transformación, por lo que la fiabilidad de este enfoque depende del entorno de tiempo de ejecución. – jevon
no sé sobre IE8 - pero IE11 funciona bien con una advertencia, parece que no puedo hacer que funcione soltando el archivo XSD en él. Sin embargo, si el archivo se sirve a través de un servidor web funciona bien ... cuando presiono el botón IE en intellidia IDEA mientras veo el XSD, lo envía a través de localhost, por lo que se procesa correctamente. Me ahorra la molestia de instalar Firefox. Dado que Chrome no funcionará para mí. Mi mayor sueño sería encontrar algo como x3sp, pero eso no mezcla toda la documentación ... mejor, déjalo en la misma posición que estaba en el XSD (debajo del elemento fue colocado después) – ycomp
Si está listo para ahondar en las complejidades de Sandcastle, le recomiendo XML Schema Documenter que es un complemento para la excelente Sandcastle Help File Builder.
Los posibles resultados son los mismos que Castillo de arena: un sitio web, un archivo de ayuda HTML (CHM), MS Help 2 contenido, MS Help Viewer 1 ...
Si no estuviera 2 años de retraso, diría 'cerca' porque es un duplicado de http://stackoverflow.com/questions/202049/formatting-xsd-scheme-for-peer-review – f3lix