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