(Quick Reference)

3.6 Documentación del projecto - Reference Documentation

Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith

Version: null

3.6 Documentación del projecto

Since Grails 1.2, the documentation engine that powers the creation of this documentation has been available for your own Grails projects.

The documentation engine uses a variation on the Textile syntax to automatically create project documentation with smart linking, formatting etc.

Creating project documentation

To use the engine you need to follow a few conventions. First, you need to create a src/docs/guide directory where your documentation source files will go. Then, you need to create the source docs themselves. Each chapter should have its own gdoc file as should all numbered sub-sections. You will end up with something like:

Desde Grails 1.2, el motor de documentación usado para la creación de esta documentación ha estado disponible para sus propios proyectos de Grails.

El motor de documentación utiliza una variación de la sintaxis de Textile para crear automáticamente la documentación del proyecto con enlaces, formato, etc..

Creación de documentación del proyecto

Para utilizar el motor tiene que seguir unos convenios. En primer lugar, debe crear a un directorio src/docs/guide donde irán sus archivos de documentación. A continuación, debe crear a los documentos propiamente. Cada capítulo debe tener su propio archivo de gdoc así como las subsecciones. Acabará con algo así como:

+ src/docs/guide/introduction.gdoc
+ src/docs/guide/introduction/changes.gdoc
+ src/docs/guide/gettingStarted.gdoc
+ src/docs/guide/configuration.gdoc
+ src/docs/guide/configuration/build.gdoc
+ src/docs/guide/configuration/build/controllers.gdoc

Note that you can have all your gdoc files in the top-level directory if you want, but you can also put sub-sections in sub-directories named after the parent section - as the above example shows.

Once you have your source files, you still need to tell the documentation engine what the structure of your user guide is going to be. To do that, you add a src/docs/guide/toc.yml file that contains the structure and titles for each section. This file is in YAML format and basically represents the structure of the user guide in tree form. For example, the above files could be represented as:

Tenga en cuenta que puede tener todos los archivos gdoc en el directorio de nivel superior si quiere, pero también puede poner subsecciones en subdirectorios después de la sección principal, como se muestra en el ejemplo anterior.

Una vez que tenga los archivos origen, aún necesita decirle al motor de documentación lo que va a ser la estructura de la Guía de Usuario. Para hacerlo, debe agregar un archivo src/docs/guide/toc.yml que contiene la estructura y los títulos de cada sección. Este archivo está en formato YAML y básicamente representa la estructura de la Guía de Usuario en forma de árbol. Por ejemplo, los archivos anteriores podrían representarse como:

introduction:
  title: Introduction
  changes: Change Log
gettingStarted: Getting Started
configuration:
  title: Configuration
  build:
    title: Build Config
    controllers: Specifying Controllers

The format is pretty straightforward. Any section that has sub-sections is represented with the corresponding filename (minus the .gdoc extension) followed by a colon. The next line should contain title: plus the title of the section as seen by the end user. Every sub-section then has its own line after the title. Leaf nodes, i.e. those without any sub-sections, declare their title on the same line as the section name but after the colon.

That's it. You can easily add, remove, and move sections within the toc.yml to restructure the generated user guide. You should also make sure that all section names, i.e. the gdoc filenames, should be unique since they are used for creating internal links and for the HTML filenames. Don't worry though, the documentation engine will warn you of duplicate section names.

Creating reference items

Reference items appear in the Quick Reference section of the documentation. Each reference item belongs to a category and a category is a directory located in the src/docs/ref directory. For example, suppose you have defined a new controller method called renderPDF. That belongs to the Controllers category so you would create a gdoc text file at the following location:

El formato es bastante sencillo. Cualquier sección que tiene subsecciones se representa con el nombre de archivo correspondiente (menos la extensión .gdoc) seguido de dos puntos. La siguiente línea debe contener title: además el título de la sección como lo verá el usuario final. Así, cada subsección tiene su propia línea después del título. Los nodos hoja, es decir, aquellos sin ningún subsección, declaran su título en la misma línea que el nombre de sección pero después de los dos puntos.

Eso es todo. Puede agregar, eliminar y mover secciones dentro de toc.yml para reestructurar la Guía de Usuario generada. También debe asegurarse de que todos los nombres de sección, es decir, los nombres de los archivos gdoc, deben ser únicos, ya que se utilizan para crear enlaces internos y los nombres de archivo HTML. No se preocupe de ello, porque el motor de documentación le avisará de los nombres de sección duplicados.

Creación de elementos de referencia

Elementos de referencia aparecen en la sección de referencia rápida de la documentación. Cada elemento de referencia pertenece a una categoría y una categoría es un directorio ubicado en el directorio src/docs/ref. Por ejemplo, suponga que ha definido un nuevo método de controlador llamado renderPDF. Pertenece a la categoría controladores por lo que debe crear un archivo de texto gdoc en la siguiente ubicación:

+ src/docs/ref/Controllers/renderPDF.gdoc

Configuring Output Properties

There are various properties you can set within your grails-app/conf/Config.groovy file that customize the output of the documentation such as:

  • grails.doc.authors - The authors of the documentation
  • grails.doc.license - The license of the software
  • grails.doc.copyright - The copyright message to display
  • grails.doc.footer - The footer to use

Configuración de las propiedades de salida

Hay varias propiedades que se pueden definir en el archivo grails-app/conf/Config.groovy que personalizan el resultado de la documentación, como:

  • grails.doc.authors - los autores de la documentación
  • grails.doc.license - la licencia del software
  • grails.doc.copyright - el mensaje de copyright para mostrar
  • grails.doc.footer - el pie de página para utilizar

Other properties such as the name of the documentation and the version are pulled from your project itself.

Generating Documentation

Once you have created some documentation (refer to the syntax guide in the next chapter) you can generate an HTML version of the documentation using the command:

Otras propiedades como el nombre de la versión y la documentación son extraídos de su propio proyecto.

Generación de documentación

Una vez haya creado alguna documentación (consulte la Guía de sintaxis en el capítulo siguiente) puede generar una versión HTML de la documentación mediante el comando:

grails doc

This command will output an docs/manual/index.html which can be opened in a browser to view your documentation.

Documentation Syntax

As mentioned the syntax is largely similar to Textile or Confluence style wiki markup. The following sections walk you through the syntax basics.

Basic Formatting

Este comando generará un docs/manual/index.html que se puede abrir en un navegador para ver la documentación.

Sintaxis de documentación

Como se ha mencionado, la sintaxis es muy similar al estilo de marcado de wiki de Textile o Confluence. Las siguientes secciones le guían a través de los fundamentos de la sintaxis.

Formato básico

Monospace: monospace

@monospace@

Cursiva: italic

_italic_

Negrita: bold

*bold*

Cursiva: italic

_italic_

Image:

!http://grails.org/images/new/grailslogo_topNav.png!

Linking

There are several ways to create links with the documentation generator. A basic external link can either be defined using confluence or textile style markup:

[SpringSource|http://www.springsource.com/]

or

"SpringSource":http://www.springsource.com/

Enlazando

Hay varias formas de crear vínculos con el generador de documentación. Un enlace externo básico puede definirse mediante el estilo marcado de Confluence o Textile:

[SpringSource|http://www.springsource.com/]

o

"SpringSource":http://www.springsource.com/

For links to other sections inside the user guide you can use the guide: prefix with the name of the section you want to link to:

[Intro|guide:introduction]

The section name comes from the corresponding gdoc filename. The documentation engine will warn you if any links to sections in your guide break.

To link to reference items you can use a special syntax:

Para enlaces a otras secciones dentro de la Guía de Usuario puede utilizar el prefijo guide: con el nombre de la sección que desea enlazar:

[Intro|guide:introduction]

El nombre de sección proviene el nombre del archivo gdoc correspondiente. El motor de documentación le avisará si se rompen los vínculos a las secciones de la guía.

Puede utilizar una sintaxis especial para vincular a elementos de referencia:

[controllers|renderPDF]

In this case the category of the reference item is on the left hand side of the | and the name of the reference item on the right.

Finally, to link to external APIs you can use the api: prefix. For example:

En este caso la categoría del elemento de referencia es el lado izquierdo de la | y el nombre del elemento de referencia es el de la derecha.

Finalmente, para vincular a las API externas puede utilizar el prefijo api:. Por ejemplo:

[String|api:java.lang.String]

The documentation engine will automatically create the appropriate javadoc link in this case. To add additional APIs to the engine you can configure them in grails-app/conf/Config.groovy. For example:

grails.doc.api.org.hibernate=
            "http://docs.jboss.org/hibernate/stable/core/javadocs"

The above example configures classes within the org.hibernate package to link to the Hibernate website's API docs.

El motor de documentación creará automáticamente el vínculo javadoc apropiado en este caso. Para agregar APIs adicionales al motor se puede configurar en grails-app/conf/Config.groovy. Por ejemplo:

grails.doc.api.org.hibernate=
            "http://docs.jboss.org/hibernate/stable/core/javadocs"

En el ejemplo anterior se configurán las clases dentro del paquete de org.hibernate para vincular documentos de APIs del sitio web de Hibernate.

Lists and Headings

Headings can be created by specifying the letter 'h' followed by a number and then a dot:

h3.<space>Heading3
h4.<space>Heading4

Unordered lists are defined with the use of the * character:

Listas y cabeceras

Las cabeceras pueden crearse mediante la especificación de la letra 'h' seguido de un número y un punto:

h3.<space>Título3
h4.<space>Heading4

Las listas desordenadas se definen con el uso del carácter :

* item 1
** subitem 1
** subitem 2
* item 2

Numbered lists can be defined with the # character:

Las listas numeradas pueden definirse con el carácter #:

# item 1

Tables can be created using the table macro:

NameNumber
Albert46
Wilma1348
James12

Las tablas pueden ser generadas usando la macro table:

NameNumber
Albert46
Wilma1348
James12

{table}
 *Nombre* | *Número*
 Albert | 46
 Wilma | 1348
 James | 12
{table}

Code and Notes

You can define code blocks with the code macro:

Código y notas

Puede definir bloques de código con la macro code:

class Book {
    String title
}

{code}
class Book {
    String title
}
{code}

The example above provides syntax highlighting for Java and Groovy code, but you can also highlight XML markup:

El ejemplo anterior proporciona resaltado de sintaxis para código Java y Groovy, pero también puede resaltar código XML:

<hello>world</hello>

{code:xml}
<hello>world</hello>
{code}

There are also a couple of macros for displaying notes and warnings:

También hay un par de macros para mostrar notas y avisos:

Note:

This is a note!

{note}
This is a note!
{note}

Warning:

Advertencia:

This is a warning!

{warning}
This is a warning!
{warning}