1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
#################################
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
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
|
