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