diff options
Diffstat (limited to 'user_guide_src/source/documentation/index.rst')
| -rw-r--r-- | user_guide_src/source/documentation/index.rst | 202 |
1 files changed, 0 insertions, 202 deletions
diff --git a/user_guide_src/source/documentation/index.rst b/user_guide_src/source/documentation/index.rst deleted file mode 100644 index aaac33ecb..000000000 --- a/user_guide_src/source/documentation/index.rst +++ /dev/null @@ -1,202 +0,0 @@ -################################# -Writing CodeIgniter Documentation -################################# - -CodeIgniter uses Sphinx to generate its documentation in a variety of formats, -using reStructuredText to handle the formatting. If you are familiar with -Markdown or Textile, you will quickly grasp reStructuredText. The focus is -on readability and user friendliness. -While they can be quite technical, we always write for humans! - -A local table of contents should always be included, like the one below. -It is created automatically by inserting the following: - -:: - - .. contents:: - :local: - - .. raw:: html - - <div class="custom-index container"></div> - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -The <div> that is inserted as raw HTML is a hook for the documentation's -JavaScript to dynamically add links to any function and method definitions -contained in the current page. - -************** -Tools Required -************** - -To see the rendered HTML, ePub, PDF, etc., you will need to install Sphinx -along with the PHP domain extension for Sphinx. The underlying requirement -is to have Python installed. Lastly, you will install the CI Lexer for -Pygments, so that code blocks can be properly highlighted. - -.. code-block:: bash - - easy_install "sphinx==1.2.3" - easy_install "sphinxcontrib-phpdomain==0.1.3.post1" - -Then follow the directions in the README file in the :samp:`cilexer` folder -inside the documentation repository to install the CI Lexer. - - - -***************************************** -Page and Section Headings and Subheadings -***************************************** - -Headings not only provide order and sections within a page, but they also -are used to automatically build both the page and document table of contents. -Headings are formed by using certain characters as underlines for a bit of -text. Major headings, like page titles and section headings also use -overlines. Other headings just use underlines, with the following hierarchy:: - - # with overline for page titles - * with overline for major sections - = for subsections - - for subsubsections - ^ for subsubsubsections - " for subsubsubsubsections (!) - -The :download:`TextMate ELDocs Bundle <./ELDocs.tmbundle.zip>` can help you -create these with the following tab triggers:: - - title-> - - ########## - Page Title - ########## - - sec-> - - ************* - Major Section - ************* - - sub-> - - Subsection - ========== - - sss-> - - SubSubSection - ------------- - - ssss-> - - SubSubSubSection - ^^^^^^^^^^^^^^^^ - - sssss-> - - SubSubSubSubSection (!) - """"""""""""""""""""""" - - - - -******************** -Method Documentation -******************** - -When documenting class methods for third party developers, Sphinx provides -directives to assist and keep things simple. -For example, consider the following ReST: - -.. code-block:: rst - - .. 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 - - -It creates the following display: - -.. 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 |