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.
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..Creating project documentation
To use the engine you need to follow a few conventions. First, you need to create asrc/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:Creación de documentación del proyecto
Para utilizar el motor tiene que seguir unos convenios. En primer lugar, debe crear a un directoriosrc/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
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 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: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
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: 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 thesrc/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: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 directoriosrc/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 yourgrails-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 archivograils-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.
Otras propiedades como el nombre de la versión y la documentación son extraídos de su propio proyecto.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: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
Este comando generará un 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
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@
_italic_
*bold*
_italic_

!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/]
"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/]
"SpringSource":http://www.springsource.com/
For links to other sections inside the user guide you can use the 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: prefix with the name of the section you want to link to:[Intro|guide:introduction]
guide: con el nombre de la sección que desea enlazar:[Intro|guide:introduction]
[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
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: prefix. For example: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 The above example configures classes within the
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. For example:grails.doc.api.org.hibernate=
"http://docs.jboss.org/hibernate/stable/core/javadocs"org.hibernate package to link to the Hibernate website's API docs.grails-app/conf/Config.groovy. Por ejemplo:grails.doc.api.org.hibernate=
"http://docs.jboss.org/hibernate/stable/core/javadocs"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
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
* 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
Las tablas pueden ser generadas usando la macro table macro:| Name | Number |
|---|---|
| Albert | 46 |
| Wilma | 1348 |
| James | 12 |
table:| Name | Number |
|---|---|
| Albert | 46 |
| Wilma | 1348 |
| James | 12 |
{table}
*Nombre* | *Número*
Albert | 46
Wilma | 1348
James | 12
{table}Code and Notes
You can define code blocks with thecode macro:Código y notas
Puede definir bloques de código con la macrocode: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}
