# 编写 CodeIgniter 的文档

CodeIgniter 使用 Sphinx 来生成多种不同格式的文档，并采用 reStructuredText 语法来编写。 如果你熟悉 Markdown 或 Textile ，你会很快上手 reStructuredText 。我们的目标是可读性 以及对用户的友好性，尽管是非常技术性的文档，但读它的永远是人类！

每一页都应该包含该页的一个目录，就像下面这样。它是通过下面的代码自动创建的：

    .. contents::
        :local:

    .. raw:: html

    <div class="custom-index container"></div>

- 所需工具
- 页面标题、小节标题 和 子标题
- 为方法编写文档

其中的 <div> 标签采用了原始的 HTML 语法，它是文档中的一个占位符，用于 JavaScript 动态的添加当前页面上的任何方法和函数。

## 所需工具

要生成 HTML、ePub、PDF 等等这些格式的文档，你需要先安装 Sphinx 和 Sphinx 的 phpdomain 扩展，并确保你已经安装了 Python 。然后安装 CI Lexer for Pygments ，它可以正确的高亮 页面中的代码。

    easy_install "sphinx==1.2.3"
    easy_install "sphinxcontrib-phpdomain==0.1.3.post1"

然后按照 `cilexer` 目录下的 README 文件的提示，来安装 CI Lexer 。

## 页面标题、小节标题 和 子标题

在一个页面中标题可以用于对内容进行排序，将内容分成章节，而且还可以用于自动生成 页面目录以及整个文档的目录。可以使用特定的某些字符作为下划线来表示标题，主标题 （例如页面标题和小节标题）还需要使用上划线，其他的标题只需要使用下划线即可。 层次结构如下:

    # 页面标题（带上划线）
    * 小节标题（带上划线）
    = 子标题
    - 子子标题
    ^ 子子子标题
    " 子子子子标题 (!)

使用 `TextMate ELDocs Bundle` 可以用下面这些 tab 快捷键快速创建这些标题:

    title->

        ##########
        Page Title
        ##########

    sec->

        *************
        Major Section
        *************

    sub->

        Subsection
        ==========

    sss->

        SubSubSection
        -------------

    ssss->

        SubSubSubSection
        ^^^^^^^^^^^^^^^^

    sssss->

        SubSubSubSubSection (!)
        """""""""""""""""""""""

## 为方法编写文档

当你为其他开发者编写类或方法的文档时，Sphinx 提供了一些指令可以帮你简单快速的完成。 例如，看下面的 ReST 语法：

    .. php:class:: Some_class

        .. php:method:: some_method ( $foo [, $bar [, $bat]])

            This function will perform some action. The ``$bar`` array must contain
            a something and something else, and along with ``$bat`` is an optional
            parameter.

            :param int $foo: the foo id to do something in
            :param mixed $bar: A data array that must contain a something and something else
            :param bool $bat: whether or not to do something
            :returns: FALSE on failure, TRUE if successful
            :rtype: bool

            ::

                $this->load->library('some_class');

                $bar = array(
                    'something'     => 'Here is this parameter!',
                    'something_else'    => 42
                );

                $bat = $this->some_class->should_do_something();

                if ($this->some_class->some_method(4, $bar, $bat) === FALSE)
                {
                    show_error('An Error Occurred Doing Some Method');
                }

            .. note:: Here is something that you should be aware of when using some_method().
                    For real.

            See also :meth:`Some_class::should_do_something`

        .. php:method:: should_do_something()

            :returns: Whether or not something should be done
            :rtype: bool

它生成的文档如下所示：

class `Some_class`
  `some_method`($foo[, $bar[, $bat]])

    This function will perform some action. The `$bar` array must contain a something and something else, and along with `$bat` is an optional parameter.

    参数: | $foo (int) -- the foo id to do something in $bar (mixed) -- A data array that must contain a something and something else $bat (bool) -- whether or not to do something
    返回: | FALSE on failure, TRUE if successful
    返回类型: | bool

        $this->load->library('some_class');

        $bar = array(
            'something'     => 'Here is this parameter!',
            'something_else'    => 42
        );

        $bat = $this->some_class->should_do_something();

        if ($this->some_class->some_method(4, $bar, $bat) === FALSE)
        {
            show_error('An Error Occurred Doing Some Method');
        }

    注解

    Here is something that you should be aware of when using some_method(). For real.

    See also `Some_class::should_do_something()`

  `should_do_something`()

    返回: | Whether or not something should be done
    返回类型: | bool