summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/documentation/index.rst
diff options
context:
space:
mode:
authorKyle Farris <kylefarris@kylefarris.gotdns.org>2011-10-14 21:43:25 +0200
committerKyle Farris <kylefarris@kylefarris.gotdns.org>2011-10-14 21:43:25 +0200
commitad17f4b932b3728c1e299b48f28b3ae0dbdd6b0b (patch)
treefdb357433e76000bdef60c4d18e5ab0540b07aeb /user_guide_src/source/documentation/index.rst
parentdb46d02ac23b8e0bc2416e197494d3b795b57530 (diff)
parenta2125a5d830fd390b4cf35f77e9bb0558cfa2dd7 (diff)
Merged with development
Diffstat (limited to 'user_guide_src/source/documentation/index.rst')
-rw-r--r--user_guide_src/source/documentation/index.rst195
1 files changed, 195 insertions, 0 deletions
diff --git a/user_guide_src/source/documentation/index.rst b/user_guide_src/source/documentation/index.rst
new file mode 100644
index 000000000..e977566d2
--- /dev/null
+++ b/user_guide_src/source/documentation/index.rst
@@ -0,0 +1,195 @@
+#################################
+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, user friendliness, and an "I've got your hand, baby" feel.
+While they can be quite technical, we always write for humans!
+
+A table of contents should always be included like the one below.
+It is created automatically by inserting the ``.. contents::``
+directive on a line by itself.
+
+.. contents:: Page Contents
+
+
+**************
+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
+ easy_install sphinxcontrib-phpdomain
+
+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
+
+ some_method()
+ =============
+
+ .. 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 aa something and something else
+ :param bool $bat: whether or not to do something
+ :returns: FALSE on failure, TRUE if successful
+ :rtype: Boolean
+
+ ::
+
+ $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 :php:meth:`Some_class::should_do_something`
+
+ should_do_something()
+ =====================
+
+ .. php:method:: should_do_something()
+
+ :returns: whether or something should be done or not
+ :rtype: Boolean
+
+
+It creates the following display:
+
+.. php:class:: Some_class
+
+some_method()
+=============
+
+ .. 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 aa something and something else
+ :param bool $bat: whether or not to do something
+ :returns: FALSE on failure, TRUE if successful
+ :rtype: Boolean
+
+ ::
+
+ $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 :php:meth:`Some_class::should_do_something`
+
+should_do_something()
+=====================
+
+ .. php:method:: should_do_something()
+
+ :returns: whether or something should be done or not
+ :rtype: Boolean