javascript - ejemplo - restful estandar

¿Cómo puedo generar documentación de API de JavaScript para páginas GitHub

Question

Hay muchas opciones excelentes para generar documentación de API para otros idiomas, pero todavía no he encontrado una solución para mi API de JavaScript que deseo alojar en GitHub Pages. Parece que puedo usar JSDoc3 pero necesitaría crear un complemento personalizado que genere el marcado Jekyll.

También me gustaría que las URL del código se vinculen a GitHub. Encontré jsdoc-githubify que controlará la salida para cambiar los enlaces, pero preferiría una opción más directa donde tenga más control.

¿Tengo que crear mi propio plugin JSDoc, o hay una mejor solución que he echado de menos? ¿Qué usan las personas para esto?

Answer 1

Aunque no lo he actualizado en mucho tiempo, https://github.com/punkave/dox-foundation es otra opción. Simplemente generará archivos HTML que podría asignar a su rama gh-pages .

Answer 2

Creo que esto es lo que estás buscando: http://jsdox.org/

jsdox es un generador jsdoc 3 simple. Extrae las etiquetas de documentación basadas en un subconjunto de jsdoc 3 de los archivos javascript y genera archivos de reducción.

Answer 3

Soy un fan de swagger: https://github.com/swagger-api/swagger-ui & http://swagger.io/ .

Incluye más que solo documentación de la API, por lo que tal vez sea exagerado para usted, pero hace un trabajo excelente al documentar las API.

Answer 4

tratando de simplificarlo

• En las páginas de GitHub que generan documentación API que genera el marcado Jekyll.

  Escape de la plantilla líquida con la etiqueta {% raw %} .

  {% raw %}
     I want to be {{escaped}}.
  {% endraw %}

  ref: github / .com / Shopify / liquid / wiki / Liquid-for-Designers # raw

  ref: jekyllrb / .com / docs / github-pages / # project-pages

  cree dos ramas, una para el maestro uno para gh-páginas, la rama maestra contiene su archivo .md y las páginas gh contienen el archivo .html generado estáticamente. En la computadora local: la $ jekyll build en la carpeta del proyecto actual se generará en ./_site .

  subir a GitHub.

  jekyll

  • rama principal: github / .com / jekyll / jekyll
  • gh-pages branch: github / .com / jekyll / jekyll / tree / gh-pages

  fb / reaccionar

  • rama principal: github / .com / facebook / reaccionar / editar / master / docs / docs / ref-01-top-level-api.md
  • gh-pages branch: github / .com / facebook / reaccionar / blob / gh-pages / docs / top-level-api.html

Las URL de las páginas enlazan al documento de GitHub en sí.

En la carpeta _layouts (plantilla html) Agregue el enlace "Editar en GitHub" en las páginas de los documentos, esta es una publicación de blog al respecto

Answer 5

http://jsdox.org/ es exactamente lo que estás buscando.

Answer 6

Si está familiarizado con Grunt , puede generar fácilmente documentos .html con grunt-jsdoc .

• Documente su código con JSDoc .
• Use grunt-jsdoc que internamente usa JSDoc3 para generar la documentación del código.
• Esto también generará el código fuente en HTML y dentro de la documentación incluirá enlaces a líneas de código para cada miembro de acceso público.
• También puede tener control sobre los enlaces simplemente usando la directiva @link de JSDoc:
  See {@link https://github.com/onury|My GitHub Profile} .

Vea un ejemplo de Gruntfile a continuación.
Tenga en cuenta que esto es compatible con todas las opciones de JSDoc CLI .

grunt.initConfig({
    ''jsdoc'': {
        dist: {
            src: [''./src/core/mylib.js''],
            options: {
                destination: ''./doc/html''
            }
        }
    }
});

Y ejecuta esta tarea con grunt jsdoc . O puede agregar el complemento grunt-contrib-watch para que se ejecute automáticamente cada vez que cambie el archivo.

Plantillas y estilo:

• Siempre puede jugar con el archivo CSS y sobrescribirlo para su propio gusto.
• O puede usar la plantilla docstrap para JSDoc3 basada en Bootstrap que se puede usar con grunt-jsdoc .

Usando Jekyll para la documentación:

Aunque es compatible de forma nativa, no tiene que usar Jekyll para GitHub Pages. Jekyll está diseñado para sitios web estáticos o blogs. Pero puede llevar archivos de rebajas. Entonces, primero crearía archivos de marcas de github con sabor desde el código a través de jsdoc-to-markdown (también hay un complemento Grunt grunt-jsdoc2md ) y luego configure un proyecto Jekyll en consecuencia.

Pero ten en cuenta que necesitarás hacer un trabajo extra para instalar y configurar Jekyll. Aquí hay un buen article y un proyecto de muestra para comenzar.

ACTUALIZAR:

Después de responder esto, comencé a trabajar en una herramienta para crear documentación fácilmente. Ahora, es lo suficientemente maduro como para publicar aquí y ver si te gusta. Se llama Docma .

Las características clave de Docma son; puede analizar los archivos JSDoc y Markdown en la documentación HTML, genera una aplicación web, es extremadamente configurable y funciona muy bien con Github Pages .

Consulte la documentación de Docma aquí , que también se ha creado con Docma y se encuentra en las páginas de GitHub.

Una captura de pantalla de muestra de SPA generado por Docma: