1 | RTEMS Project Documentation |
---|
2 | =========================== |
---|
3 | |
---|
4 | The documents are written in ReST and built using Sphinx. The build system will |
---|
5 | check the version of Sphinx and ensure you have a suitable version |
---|
6 | available. If your host does not provide a packaged version use PIP to fetch a |
---|
7 | recent version. The Sphinx website provides details on doing this. |
---|
8 | |
---|
9 | ReST is the Re-Structed-Text format. It is a simple markup language that allows |
---|
10 | us to create quality documentaion. It is flexible and powerful however do not |
---|
11 | attempt to train it to create a specific format. You need to test any new way |
---|
12 | of presenting something on all output formats. What may look great in one |
---|
13 | format may not translate with the same clarity to another output format. |
---|
14 | |
---|
15 | The RTEMS Documentation output formats are: |
---|
16 | |
---|
17 | HTML - Multi-page HTML with files in a single directory per manual. |
---|
18 | PDF - Single PDF per manual. |
---|
19 | SIngle HTML - Single HTML, one file per manual. |
---|
20 | |
---|
21 | The PDF format is cerated using Latex and that uses texlive packages. This |
---|
22 | exposes us to the complex world of Latex however the quality of the documents |
---|
23 | created is worth it. |
---|
24 | |
---|
25 | Production Quality Hosts |
---|
26 | ------------------------ |
---|
27 | |
---|
28 | We allow the building of PDF documentation on hosts that do not have a fully |
---|
29 | suitable texlive environment and this results in quality that is not at the |
---|
30 | production level. |
---|
31 | |
---|
32 | The hosts which produce production quality is: |
---|
33 | |
---|
34 | FreeBSD |
---|
35 | CentOS 6 and 7 (if using texlive, not RPMs of texlive) |
---|
36 | |
---|
37 | Host Setup |
---|
38 | ---------- |
---|
39 | |
---|
40 | HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install, |
---|
41 | and building a Single HTML page requires the 'inliner' tool. |
---|
42 | |
---|
43 | Please add your host as you set it up. |
---|
44 | |
---|
45 | Sphinx Per User Install |
---|
46 | ~~~~~~~~~~~~~~~~~~~~~~~ |
---|
47 | |
---|
48 | You can use this method to install a personal version of Sphinx if your host |
---|
49 | does not provide a suitable package: |
---|
50 | |
---|
51 | $ pip install -U sphinx |
---|
52 | |
---|
53 | On some hosts, this may complain that a newer version of pip is available. |
---|
54 | If so, then upgrade pip into your personal area. |
---|
55 | |
---|
56 | $ pip install --upgrade --user pip |
---|
57 | |
---|
58 | The personal area for these tools is ${HOME}/.local/bin. It should |
---|
59 | be PREPENDED to your path. On a 32-bit install of CentOS 6, these |
---|
60 | were the PATH modifications to use the local install of Texlive |
---|
61 | and sphinx: |
---|
62 | |
---|
63 | export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH} |
---|
64 | export PATH=${HOME}/.local/bin:${PATH} |
---|
65 | |
---|
66 | FreeBSD |
---|
67 | ~~~~~~~ |
---|
68 | |
---|
69 | PDF Quality: production |
---|
70 | |
---|
71 | Sphinx: |
---|
72 | |
---|
73 | # pkg install py27-sphinx |
---|
74 | |
---|
75 | PDF: |
---|
76 | |
---|
77 | # pkg install texlive-full |
---|
78 | |
---|
79 | Single HTML: |
---|
80 | |
---|
81 | # pkg install npm |
---|
82 | # npm install -g inliner |
---|
83 | |
---|
84 | CentOS 6 and 7 |
---|
85 | ~~~~~~~~~~~~~~ |
---|
86 | |
---|
87 | PDF Quality: production |
---|
88 | |
---|
89 | Sphinx: |
---|
90 | |
---|
91 | $ pip install -U sphinx |
---|
92 | |
---|
93 | PDF: |
---|
94 | |
---|
95 | WARNING: Do NOT use the RPMs for texlive. They are incomplete and, in |
---|
96 | the best case, result in ugly PDFs. |
---|
97 | |
---|
98 | As root, install texlive per the instructions at |
---|
99 | http://tug.org/texlive/acquire-netinstall.html |
---|
100 | |
---|
101 | # wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz |
---|
102 | # tar xf install-tl-unx.tar.gz |
---|
103 | # cd install-tl-20161106 |
---|
104 | NOTE: The date in the name of the directory will change. |
---|
105 | # ./install-tl |
---|
106 | - Use the command line system. Select "O" for options if you want to |
---|
107 | change from A4 to US letter paper size by default. |
---|
108 | - Select "I" to install |
---|
109 | - The tools will be installed into a directory like the following: |
---|
110 | /usr/local/texlive/2016/bin/i386-linux/ |
---|
111 | |
---|
112 | NOTE: The year (2016) and host OS (i386-linux) will change to |
---|
113 | reflect 32 or 64 bit and OS name. |
---|
114 | |
---|
115 | Single HTML: |
---|
116 | |
---|
117 | # yum install npm |
---|
118 | # npm install -g inliner |
---|
119 | |
---|
120 | PATH: |
---|
121 | |
---|
122 | Ensure the appropriate directories are PREPENDED to your PATH before |
---|
123 | building the documentation. Examples are shown below: |
---|
124 | |
---|
125 | export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH} |
---|
126 | export PATH=${HOME}/.local/bin:${PATH} |
---|
127 | |
---|
128 | |
---|
129 | Arch Linux |
---|
130 | ~~~~~~~~~~ |
---|
131 | |
---|
132 | Sphinx: |
---|
133 | |
---|
134 | # pacman -S python-sphinx |
---|
135 | |
---|
136 | PDF: |
---|
137 | |
---|
138 | # pacman -S texlive-bin texlive-core texlive-latexextra texlive-fontsextra \ |
---|
139 | |
---|
140 | openSUSE |
---|
141 | ~~~~~~~~ |
---|
142 | |
---|
143 | Packages: |
---|
144 | |
---|
145 | # zypper in python-pip 'texlive*' |
---|
146 | |
---|
147 | Sphinx: |
---|
148 | |
---|
149 | # pip install -U Sphinx |
---|
150 | |
---|
151 | Using pip to install Sphinx destroys the python-Sphinx package if installed via |
---|
152 | RPM. |
---|
153 | |
---|
154 | Latex Setup |
---|
155 | ~~~~~~~~~~~ |
---|
156 | |
---|
157 | Latex is used to create the PDF document. The setup of Latex varies from host |
---|
158 | to host operating system due to the way each host packages the texlive |
---|
159 | packages. There is no common naming and no real way to figure what texlive |
---|
160 | package is present in a host's packaging. It seems not all of texlive is |
---|
161 | available. |
---|
162 | |
---|
163 | The RTEMS Documentation waf configure phase check for each texlive package used |
---|
164 | in the generated output and the styles. If you complete configure with the |
---|
165 | --pdf option you should be able to build PDF documentation. |
---|
166 | |
---|
167 | The texlive package requirments come from the Latex styles we are using and |
---|
168 | Sphinx. |
---|
169 | |
---|
170 | An example of failures are: |
---|
171 | |
---|
172 | Checking for Tex package 'Bjarne' : ok |
---|
173 | Checking for Tex package 'alltt' : ok |
---|
174 | Checking for Tex package 'amsmath' : ok |
---|
175 | Checking for Tex package 'amssymb' : ok |
---|
176 | Checking for Tex package 'amstext' : ok |
---|
177 | Checking for Tex package 'array' : ok |
---|
178 | Checking for Tex package 'atbegshi' : ok |
---|
179 | Checking for Tex package 'babel' : ok |
---|
180 | Checking for Tex package 'calc' : ok |
---|
181 | Checking for Tex package 'capt-of' : not found (please install) |
---|
182 | Checking for Tex package 'charter' : ok |
---|
183 | Checking for Tex package 'cmap' : ok |
---|
184 | Checking for Tex package 'color' : ok |
---|
185 | Checking for Tex package 'eqparbox' : not found (please install) |
---|
186 | Checking for Tex package 'etoolbox' : ok |
---|
187 | Checking for Tex package 'fancybox' : ok |
---|
188 | Checking for Tex package 'fancyhdr' : ok |
---|
189 | Checking for Tex package 'fancyvrb' : ok |
---|
190 | Checking for Tex package 'float' : ok |
---|
191 | Checking for Tex package 'fncychap' : ok |
---|
192 | Checking for Tex package 'fontenc' : ok |
---|
193 | Checking for Tex package 'footnote' : ok |
---|
194 | Checking for Tex package 'framed' : ok |
---|
195 | Checking for Tex package 'graphicx' : ok |
---|
196 | Checking for Tex package 'hypcap' : ok |
---|
197 | Checking for Tex package 'hyperref' : ok |
---|
198 | Checking for Tex package 'ifplatform' : not found (please install) |
---|
199 | Checking for Tex package 'ifthen' : ok |
---|
200 | Checking for Tex package 'inconsolata' : not found (please install) |
---|
201 | Checking for Tex package 'inputenc' : ok |
---|
202 | Checking for Tex package 'keyval' : ok |
---|
203 | Checking for Tex package 'kvoptions' : ok |
---|
204 | Checking for Tex package 'lato' : not found (please install) |
---|
205 | Checking for Tex package 'lineno' : ok |
---|
206 | Checking for Tex package 'longtable' : ok |
---|
207 | Checking for Tex package 'makeidx' : ok |
---|
208 | Checking for Tex package 'multirow' : ok |
---|
209 | Checking for Tex package 'parskip' : ok |
---|
210 | Checking for Tex package 'pdftexcmds' : ok |
---|
211 | Checking for Tex package 'textcomp' : ok |
---|
212 | Checking for Tex package 'threeparttable' : ok |
---|
213 | Checking for Tex package 'times' : ok |
---|
214 | Checking for Tex package 'titlesec' : ok |
---|
215 | Checking for Tex package 'upquote' : not found (please install) |
---|
216 | Checking for Tex package 'utf8' : ok |
---|
217 | Checking for Tex package 'wrapfig' : ok |
---|
218 | Checking for Tex package 'xcolor' : ok |
---|
219 | Checking for Tex package 'xstring' : ok |
---|
220 | There are 6 Tex package failures. Please fix. |
---|
221 | |
---|
222 | If you find there is an issue please post the developers list. |
---|
223 | |
---|
224 | Building |
---|
225 | -------- |
---|
226 | |
---|
227 | Note: waf-1.9.5 is a little noisy when running tex builds and tests. I hope |
---|
228 | to have this resolved soon. |
---|
229 | |
---|
230 | To build enter in the top directory: |
---|
231 | |
---|
232 | $ ./waf configure [--pdf] [--singlehtml] [--prefix] [--sphinx-verbose] |
---|
233 | $ ./waf |
---|
234 | |
---|
235 | The '--pdf' and '--singlehtml' options can be added to configure to build those |
---|
236 | output formats. |
---|
237 | |
---|
238 | To build and install to a specific location: |
---|
239 | |
---|
240 | $ ./waf configure --prefix=/foo/my/location |
---|
241 | $ ./waf build install |
---|
242 | |
---|
243 | If you need to debug what is happening use configure with a suitable Sphinx |
---|
244 | version level: |
---|
245 | |
---|
246 | $ ./waf configure --sphinx-verbose=-v |
---|
247 | $ ./waf clean build |
---|
248 | |
---|
249 | You can enter a manual's directory and run the same configure command and build |
---|
250 | just that manual. |
---|
251 | |
---|
252 | Documentation Standard |
---|
253 | ---------------------- |
---|
254 | |
---|
255 | This following details the documentation standard. If in doubt first search the |
---|
256 | existing documentation for an example and if unsure ask. |
---|
257 | |
---|
258 | 1. All text is to be formatted to wrap at 80 columns. Do not manually line feed |
---|
259 | before 80. |
---|
260 | |
---|
261 | 2. Do not insert tab characters, use spaces, no trailing white space. |
---|
262 | |
---|
263 | 3. Pasted text such as console output can exceed 80 columns however it is |
---|
264 | preferred even this text is wrapped at 80 columns. Long lines in code block |
---|
265 | text causes issues with the PDF output. |
---|
266 | |
---|
267 | 4. The headings use the following: |
---|
268 | |
---|
269 | Heading Description |
---|
270 | 1 ###### Part |
---|
271 | 2 ****** Section |
---|
272 | 3 ====== Sub-ection |
---|
273 | 4 ------ Sub-sub-section |
---|
274 | 5 ^^^^^^ Sub-sub-sub-section |
---|
275 | 6 ~~~~~~ Sub-sub-sub-sub-section |
---|
276 | |
---|
277 | 5. For literal output, such as shell commands and code use '::' at the trailing |
---|
278 | edge of the previous paragraph. If the '.. code-block::' with |
---|
279 | 'c' for C code and 'shell' for shell code and terminal output. If you need |
---|
280 | line number use: |
---|
281 | |
---|
282 | .. code-block:: shell |
---|
283 | :linenos: |
---|
284 | |
---|
285 | 6. Use the directives for 'note', 'warning', and 'topic'. Do not add 'TIP', |
---|
286 | 'Important' or 'Warning' to the text. Let the mark-up language handle |
---|
287 | this. The supported directives are: |
---|
288 | |
---|
289 | .. warning:: |
---|
290 | .. note:: |
---|
291 | .. topic:: |
---|
292 | |
---|
293 | These directives reference specific CSS sytle support. |
---|
294 | |
---|
295 | 7. Images are placed in the 'images' directory. Do not place images in the |
---|
296 | source directories. Using a common 'images' tree of images promotes sharing |
---|
297 | of images. To add an image use: |
---|
298 | |
---|
299 | .. figure:: ../images/my-image.png |
---|
300 | :wdith: 75% |
---|
301 | :align: center |
---|
302 | :alt: This is the alt text for some output types. |
---|
303 | |
---|
304 | 8. Callouts can be implement manually using a liternal block which can using |
---|
305 | '::' or a code block and topic block is used for the items. For |
---|
306 | example: |
---|
307 | |
---|
308 | .. code-block: c |
---|
309 | |
---|
310 | #include <stdio.h> <1> |
---|
311 | int main(int argc, char** argv) <2> |
---|
312 | { |
---|
313 | printf("Hello world\n"); <3> |
---|
314 | return 0; <4> |
---|
315 | } |
---|
316 | |
---|
317 | .. topic:: Items: |
---|
318 | |
---|
319 | 1. Include the standard input/output header file. |
---|
320 | |
---|
321 | 2. The program starts here. |
---|
322 | |
---|
323 | 3. Print something to the standard output device. |
---|
324 | |
---|
325 | 4. Exit with an exit code of 0. This is value can be checked by the |
---|
326 | caller of this program. |
---|
327 | |
---|
328 | Note, the topic items are manually number. This makes is easier to see which |
---|
329 | item matches the text. Use <> for the number and align at a position that |
---|
330 | works and makes the number as visible as possible. Use hanging indents if an |
---|
331 | items extends over a single line. |
---|
332 | |
---|
333 | 9. Use the RTEMS domain references for URLs and mailing lists. For example to |
---|
334 | insert the RTEMS developers list use: |
---|
335 | |
---|
336 | :r:list:`devel` |
---|
337 | :r:url:`git` |
---|
338 | |
---|
339 | The valid lists are: |
---|
340 | |
---|
341 | announce : Announce Mailing List |
---|
342 | bugs : Bugs Mailing List |
---|
343 | devel : Developers Mailing List |
---|
344 | build : Build Logs |
---|
345 | users : Users Mailing List |
---|
346 | vc : Version Control Mailing List |
---|
347 | |
---|
348 | The valif URLs are: |
---|
349 | |
---|
350 | trac : https://devel.rtems.org/ |
---|
351 | devel : https://devel.rtems.org/ |
---|
352 | www : https://www.rtems.org/ |
---|
353 | buildbot : https://buildbot.rtems.org/ |
---|
354 | builder : https://builder.rtems.org/ |
---|
355 | docs : https://docs.rtems.org/ |
---|
356 | lists : https://lists.rtems.org/ |
---|
357 | git : https://git.rtems.org/ |
---|
358 | ftp : https://ftp.rtems.org/ |
---|
359 | review : https://review.rtems.org/ |
---|
360 | bugs : https://devel.rtems.org/wiki/Bugs/ |
---|
361 | gsoc : https://devel.rtems.org/wiki/GSoC/ |
---|
362 | socis : https://devel.rtems.org/wiki/SOCIS/ |
---|