summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/documentation
diff options
context:
space:
mode:
authorDerek Jones <derek.jones@ellislab.com>2011-10-05 20:34:52 +0200
committerDerek Jones <derek.jones@ellislab.com>2011-10-05 20:34:52 +0200
commit8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 (patch)
tree2e960ec3b416b477f40bb546371f2d486f4a22f0 /user_guide_src/source/documentation
parentd1ecd5cd4ae6ab5d37df9fbda14b93977b9e743c (diff)
replacing the old HTML user guide with a Sphinx-managed user guide
Diffstat (limited to 'user_guide_src/source/documentation')
-rw-r--r--user_guide_src/source/documentation/ELDocs.tmbundle.zipbin0 -> 3932 bytes
-rw-r--r--user_guide_src/source/documentation/index.rst195
2 files changed, 195 insertions, 0 deletions
diff --git a/user_guide_src/source/documentation/ELDocs.tmbundle.zip b/user_guide_src/source/documentation/ELDocs.tmbundle.zip
new file mode 100644
index 000000000..f7a11b364
--- /dev/null
+++ b/user_guide_src/source/documentation/ELDocs.tmbundle.zip
Binary files differ
diff --git a/user_guide_src/source/documentation/index.rst b/user_guide_src/source/documentation/index.rst
new file mode 100644
index 000000000..d62920f74
--- /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->EE->load->library('some_class');
+
+ $bar = array(
+ 'something' => 'Here is this parameter!',
+ 'something_else' => 42
+ );
+
+ $bat = $this->EE->some_class->should_do_something();
+
+ if ($this->EE->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->EE->load->library('some_class');
+
+ $bar = array(
+ 'something' => 'Here is this parameter!',
+ 'something_else' => 42
+ );
+
+ $bat = $this->EE->some_class->should_do_something();
+
+ if ($this->EE->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