# 編寫 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