编写 CodeIgniter 的文档

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

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

  1. .. contents::
  2.     :local:
  3.  
  4. .. raw:: html
  5.  
  6. <div class="custom-index container"></div>

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

所需工具

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

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

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

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

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

  1. # 页面标题（带上划线）
  2. * 小节标题（带上划线）
  3. = 子标题
  4. - 子子标题
  5. ^ 子子子标题
  6. " 子子子子标题 (!)

使用 TextMateELDocsBundle 可以用下面这些 tab快捷键快速创建这些标题:

  1. title->
  2.  
  3.     ##########
  4.     Page Title
  5.     ##########
  6.  
  7. sec->
  8.  
  9.     *************
  10.     Major Section
  11.     *************
  12.  
  13. sub->
  14.  
  15.     Subsection
  16.     ==========
  17.  
  18. sss->
  19.  
  20.     SubSubSection
  21.     -------------
  22.  
  23. ssss->
  24.  
  25.     SubSubSubSection
  26.     ^^^^^^^^^^^^^^^^
  27.  
  28. sssss->
  29.  
  30.     SubSubSubSubSection (!)
  31.     """""""""""""""""""""""

为方法编写文档

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

  1. .. php:class:: Some_class
  2.  
  3.     .. php:method:: some_method ( $foo [, $bar [, $bat]])
  4.  
  5.         This function will perform some action. The ``$bar`` array must contain
  6.         a something and something else, and along with ``$bat`` is an optional
  7.         parameter.
  8.  
  9.         :param int $foo: the foo id to do something in
  10.         :param mixed $bar: A data array that must contain a something and something else
  11.         :param bool $bat: whether or not to do something
  12.         :returns: FALSE on failure, TRUE if successful
  13.         :rtype: bool
  14.  
  15.         ::
  16.  
  17.             $this->load->library('some_class');
  18.  
  19.             $bar = array(
  20.                 'something'     => 'Here is this parameter!',
  21.                 'something_else'    => 42
  22.             );
  23.  
  24.             $bat = $this->some_class->should_do_something();
  25.  
  26.             if ($this->some_class->some_method(4, $bar, $bat) === FALSE)
  27.             {
  28.                 show_error('An Error Occurred Doing Some Method');
  29.             }
  30.  
  31.         .. note:: Here is something that you should be aware of when using some_method().
  32.                 For real.
  33.  
  34.         See also :meth:`Some_class::should_do_something`
  35.  
  36.  
  37.     .. php:method:: should_do_something()
  38.  
  39.         :returns: Whether or not something should be done
  40.         :rtype: bool

它生成的文档如下所示：

  • _class _Some_class
    • somemethod($foo[, $bar[, $bat_]])
    • This function will perform some action. The $bar array must containa something and something else, and along with $bat is an optionalparameter.

参数:

  1. - **$foo** (_int_) -- the foo id to do something in
  2. - **$bar** (_mixed_) -- A data array that must contain a something and something else
  3. - **$bat** (_bool_) -- whether or not to do something返回:

FALSE on failure, TRUE if successful返回类型:bool

  1. $this->load->library('some_class');
  2.  
  3. $bar = array(
  4.     'something'     => 'Here is this parameter!',
  5.     'something_else'    => 42
  6. );
  7.  
  8. $bat = $this->some_class->should_do_something();
  9.  
  10. if ($this->some_class->some_method(4, $bar, $bat) === FALSE)
  11. {
  12.     show_error('An Error Occurred Doing Some Method');
  13. }

注解

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