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

* Tools Required

* Page and Section Headings and Subheadings

* Method Documentation

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

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

Then follow the directions in the README file in the "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 "TextMate ELDocs Bundle" 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:

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

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.

      Parameters:
         * **$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

      Returns:
         FALSE on failure, TRUE if successful

      Return type:
         "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 "Some_class::should_do_something()"

   should_do_something()

      Returns:
         Whether or not something should be done

      Return type:
         "bool"
