(Quick Reference)

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 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:

+ 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:

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.

创建工程文档

为了使用此引擎,你需要遵循一些约定。首先,你需要创建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

注意,如果你喜欢,你可以将所有的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 Controllers

此种格式是相当简洁易懂的,一个章节如果含有子章节的话,要在其对应的文件名(当然是去掉.gdoc后缀)后边添加一个冒号(:),紧随其后的一行必须是title:加对此章节的标题描述,在标题后边是每一个子章节的信息。如果子章节是一个叶子节点(不包含子章节的章节)其标题跟章节名称在同一行就好了,但要以冒号分割(可以参考上述示例--译者注)。

搞定!你可以轻松地添加、删除和移动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 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:

+ 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 your grails-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

Other properties such as the version are pulled from your project itself. If a title is not specified, the application name is used.

配置输出属性

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

This command will output an 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: italic

_italic_

Bold: bold

*bold*

Image:

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

基本格式

等宽字体: monospace

@monospace@

斜体: italic

_italic_

黑体: bold

*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/]

or

"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:

[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:

[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.

超链接

文档生成链接的方式有几种,基本的外部链接(指向本文档之外的超链接--译者注)可以使用confluence或者textile风格的标签:

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

或者

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

对于指向本文档其他章节的链接,可以使用guide:前缀和你要指向的章节名称:

[Intro|guide:introduction]

章节的名称要跟gdoc文件名称相对应。如果你指向的章节不存在,文档引擎会给你一个警告提示。

要指向条目引用,你可以使用如下特殊语法:

[controllers|renderPDF]

此种情况,要引用的类别名称在|左边,而要引用的条目名称位于右边。

最后,要指向外部API,你可以使用api:前缀。比如:

[String|api:java.lang.String]

文档引擎将自动生成合适的javadoc链接。对于额外的API,你可以通过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

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

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

Numbered lists can be defined with the # character:

# item 1

Tables can be created using the table macro:

NameNumber
Albert46
Wilma1348
James12

{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来实现:

NameNumber
Albert46
Wilma1348
James12

{table}
 *Name* | *Number*
 Albert | 46
 Wilma | 1348
 James | 12
{table}

Code and Notes

You can define code blocks with the code macro:

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:

<hello>world</hello>

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

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

Note:

This is a note!

{note}
This is a note!
{note}

Warning:

This is a warning!

{warning}
This is a warning!
{warning}

代码和提示

你可以通过宏code来定义代码块,比如:

class Book {
    String title
}

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

上述示例展示了Java和Groovy代码的高亮语法显示,但是你也可以高亮XML标签,比如:

<hello>world</hello>

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

还有一些用于提示和警告的宏:

Note:

This is a note!

{note}
This is a note!
{note}

Warning:

This is a warning!

{warning}
This is a warning!
{warning}