3.6 文档引擎 - Reference Documentation
Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith
Version: null
3.6 文档引擎
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.
从Grails 1.2以来,本文的文档就是通过文档引擎来创建的,并且对你的Grails项目文档也是有效的。文档引擎在Textile语法基础上,进行了一些改动,以适应自动创建工程文档的需要,此文档支持灵活链接、格式化等功能。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:+ 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
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:introduction:
title: Introduction
changes: Change Log
gettingStarted: Getting Started
configuration:
title: Configuration
build:
title: Build Config
controllers: Specifying Controllerstitle: 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.
创建工程文档
为了使用此引擎,你需要遵循一些约定。首先,你需要创建src/docs/guide目录用来存放文档的源文件。其次,需要创建文档文件,每一章节应该是独立的一个gdoc文件,并且还应该按照子章节的序号排列。比如下面示例:+ 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
src/docs/guide/toc.yml文件,用以描述章节的结构和标题。 此YAML格式的文件用以表述手册的树形格式的结构。比如上述的文件可以用如下的描述:introduction:
title: Introduction
changes: Change Log
gettingStarted: Getting Started
configuration:
title: Configuration
build:
title: Build Config
controllers: Specifying Controllerstitle:加对此章节的标题描述,在标题后边是每一个子章节的信息。如果子章节是一个叶子节点(不包含子章节的章节)其标题跟章节名称在同一行就好了,但要以冒号分割(可以参考上述示例--译者注)。搞定!你可以轻松地添加、删除和移动toc.yml中的章节,这样就可以重新排版用户手册了。此外你也需要确认所有的章节名称(gdoc文件名称)是全局唯一的,因为那些内部超链接和HTML名称也要用到它们。不过也无需太担心,文档引擎将提示你那些重复的章节名称。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:+ src/docs/ref/Controllers/renderPDF.gdoc
创建条目(Item)引用
条目引用出现在文档的快速引用章节。每一个引用都属于一个类别,此类别位于src/docs/ref中。举例来说,假设你定义了一个新的控制器方法renderPDF,此方法属于Controllers类别,那么你应该在如下所示的位置创建一个gdoc文本文件:+ 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.title - The title of the documentation
- grails.doc.subtitle - The subtitle of the documentation
- 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
配置输出属性
在grails-app/conf/Config.groovy文件中,你有很多不同的属性可以设置,用以自定义文档的输出,比如:
- grails.doc.title - 文档的标题
- grails.doc.subtitle - 文档的子标题
- grails.doc.authors - 文档的作者
- grails.doc.license - 软件的许可证
- grails.doc.copyright - 要显示的版权信息
- grails.doc.footer - 脚注
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:grails doc
docs/manual/index.html which can be opened in a browser to view your documentation.
生成文档
一旦你创建了文档(语法请参考下一节),你就可以生成HTML版本的文档了,命令如下:grails doc
docs/manual/index.html,这样你就可以在浏览器中查看文档了。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.文档语法
正如以前所述,文档语法跟Textile或者Confluence风格的wiki标签。下述章节将对基本的语法做个简单地介绍。Basic Formatting
Monospace:monospace
@monospace@
_italic_
*bold*

!http://grails.org/images/new/grailslogo_topNav.png!
基本格式
等宽字体:monospace
@monospace@
_italic_
*bold*

!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/guide: prefix with the name of the section you want to link to:[Intro|guide:introduction]
[controllers|renderPDF]
api: prefix. For example:[String|api:java.lang.String]
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.
超链接
文档生成链接的方式有几种,基本的外部链接(指向本文档之外的超链接--译者注)可以使用confluence或者textile风格的标签:[SpringSource|http://www.springsource.com/]
"SpringSource":http://www.springsource.com/guide:前缀和你要指向的章节名称:[Intro|guide:introduction]
[controllers|renderPDF]
api:前缀。比如:[String|api:java.lang.String]
grails-app/conf/Config.groovy来进行配置,比如:grails.doc.api.org.hibernate=
"http://docs.jboss.org/hibernate/stable/core/javadocs"org.hibernate包指向Hibernate的官方API文档。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
* item 1 ** subitem 1 ** subitem 2 * item 2
# item 1
table macro:| Name | Number |
|---|---|
| Albert | 46 |
| Wilma | 1348 |
| James | 12 |
{table}
*Name* | *Number*
Albert | 46
Wilma | 1348
James | 12
{table}列表和标头
标头可以通过字母'h'加数字再加一个点来表示,比如:h3.<space>Heading3 h4.<space>Heading4
* item 1 ** subitem 1 ** subitem 2 * item 2
# item 1
table来实现:| Name | Number |
|---|---|
| Albert | 46 |
| Wilma | 1348 |
| James | 12 |
{table}
*Name* | *Number*
Albert | 46
Wilma | 1348
James | 12
{table}Code and Notes
You can define code blocks with thecode macro:class Book {
String title
}{code}
class Book {
String title
}
{code}<hello>world</hello>
{code:xml}
<hello>world</hello>
{code}This is a note!
{note}
This is a note!
{note}This is a warning!
{warning}
This is a warning!
{warning}代码和提示
你可以通过宏code来定义代码块,比如:class Book {
String title
}{code}
class Book {
String title
}
{code}<hello>world</hello>
{code:xml}
<hello>world</hello>
{code}This is a note!
{note}
This is a note!
{note}This is a warning!
{warning}
This is a warning!
{warning}
