1 | RTEMS Project Documentation |
---|
2 | =========================== |
---|
3 | |
---|
4 | The documents are written in ReST and built using Sphinx. The waf build system |
---|
5 | will 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-Structured-Text format. It is a simple markup language that |
---|
10 | allows us to create quality documentation which can easily be converted to |
---|
11 | multiple different formats. This flexibility is convenient, but you still need |
---|
12 | to test any new way of presenting something on all output formats. What may look |
---|
13 | great in one format may not translate with the same clarity to another output |
---|
14 | format. |
---|
15 | |
---|
16 | The RTEMS Documentation output formats are: |
---|
17 | |
---|
18 | HTML - Multi-page HTML with files in a single directory per manual. |
---|
19 | PDF - Single PDF per manual. |
---|
20 | Single HTML - Single HTML, one file per manual. |
---|
21 | |
---|
22 | The PDF format is created using Latex and that uses texlive packages. This |
---|
23 | exposes us to the complex world of Latex however the quality of the documents |
---|
24 | created is worth it. |
---|
25 | |
---|
26 | Images can be created from source using PlantUML and Ditaa. |
---|
27 | |
---|
28 | A Sphinx checksheet is: |
---|
29 | |
---|
30 | https://sphinx-tutorial.readthedocs.io/cheatsheet/#rst-cheat-sheet |
---|
31 | |
---|
32 | Production Quality Hosts |
---|
33 | ------------------------ |
---|
34 | |
---|
35 | We allow the building of PDF documentation on hosts that do not have a fully |
---|
36 | suitable texlive environment and this results in quality that is not at the |
---|
37 | production level. |
---|
38 | |
---|
39 | The hosts which produce production quality are: |
---|
40 | |
---|
41 | FreeBSD |
---|
42 | CentOS 6 and 7 (if using texlive, not RPMs of texlive) |
---|
43 | |
---|
44 | NOTE: RedHat Enterprise Linux (RHEL) and Fedora should be the same as CentOS. |
---|
45 | |
---|
46 | Images |
---|
47 | ------ |
---|
48 | |
---|
49 | All images should be placed in the 'images' directory and referenced from the |
---|
50 | ReST with a relative path. This lets us shared and control images. |
---|
51 | |
---|
52 | We prefer being able to build images from source. This is not always possible |
---|
53 | so SVG format is preferred with generated PNG images to make sure the quality |
---|
54 | is consistent when building PDF output. |
---|
55 | |
---|
56 | Building images requires the source with an apporoiate file extension |
---|
57 | is placed in the images directory. The built output image is written |
---|
58 | back to the images directory. All images may be built or rebuilt when |
---|
59 | building images is enabled via the waf configure command line. Please |
---|
60 | only add and commit those images that have changed. |
---|
61 | |
---|
62 | We support building images in: |
---|
63 | |
---|
64 | 1. PlantUML (.puml), enable with `--plantuml` |
---|
65 | |
---|
66 | 2. Ditaa (.ditaa), enable with `--ditaa` |
---|
67 | |
---|
68 | We support the PlantUML image language. The PlantUML home page is: |
---|
69 | |
---|
70 | http://plantuml.com/ |
---|
71 | |
---|
72 | The page as a link to an 'online demo server' you can use to create images |
---|
73 | rathre than installing PlantUML. Save you source then View and save the PNG |
---|
74 | format image. The PlantUML language reference guide is: |
---|
75 | |
---|
76 | http://plantuml.com/PlantUML_Language_Reference_Guide.pdf |
---|
77 | |
---|
78 | And the web site has online documentation. The image source extension is |
---|
79 | '.puml'. |
---|
80 | |
---|
81 | We also support Ditaa image language. The Ditaa home page is: |
---|
82 | |
---|
83 | http://ditaa.sourceforge.net/ |
---|
84 | |
---|
85 | The home page contain the language options. The PlantUML online demo server |
---|
86 | supports Ditaa so use that resource as an online tool. The Ditaa image source |
---|
87 | extension is '.ditaa'. |
---|
88 | |
---|
89 | You do not need PlantUML or Ditaa installed to build our documentation. The |
---|
90 | online resources can be used. Save the source and the generated PNG file in the |
---|
91 | same directory under 'images'. |
---|
92 | |
---|
93 | *Note:* |
---|
94 | Please consider using PlantUML and Ditaa before other tools because we |
---|
95 | can generate the images from source automatically and it gives the |
---|
96 | documentation a similar look and feel. Other options may be considered |
---|
97 | if the image cannot be easly created by PlantUML or Ditaa but please |
---|
98 | ask before starting down that path because it may not be accepted. |
---|
99 | |
---|
100 | Image editing tools tend to have a specific look and feel and this |
---|
101 | characterizes the images they create. Altering an image often means |
---|
102 | the original tool is required. An open output format allows us to |
---|
103 | integrate the image into the document however we are then required to |
---|
104 | monitor and maintain that tool if we need to make changes. The fewer |
---|
105 | alternatives we have to maintain the easier it is for the project over |
---|
106 | a long period of time. |
---|
107 | |
---|
108 | Host Setup |
---|
109 | ---------- |
---|
110 | |
---|
111 | HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install, |
---|
112 | and building a Single HTML page requires the 'inliner' tool. The |
---|
113 | sphinxcontrib-bibtex extension is mandatory. PlantUML requires the Node.js |
---|
114 | package called 'node-plantuml' which installs the 'puml' command and Ditaa needs |
---|
115 | the 'ditaa' command and package. Ditaa images are built using the 'puml' |
---|
116 | command. |
---|
117 | |
---|
118 | Please add your host to this section as you set it up. |
---|
119 | |
---|
120 | The best results are produced with Python3 and a virtual environment`. It can |
---|
121 | create a specific python environment using `pip`. |
---|
122 | |
---|
123 | Virtual Environment |
---|
124 | ~~~~~~~~~~~~~~~~~~~ |
---|
125 | |
---|
126 | Create a directory to house the virtual environment, create the environment, |
---|
127 | and then activate it. This example assumes Python3 and the `venv` module: |
---|
128 | |
---|
129 | $ mkdir sphinx |
---|
130 | $ python3 -m venv sphinx |
---|
131 | $ . ./sphinx/bin/activate |
---|
132 | |
---|
133 | Alternatively you can use the `virtualenv` command: |
---|
134 | |
---|
135 | $ mkdir sphinx |
---|
136 | $ virtualenv sphinx |
---|
137 | $ . ./sphinx/bin/activate |
---|
138 | |
---|
139 | Either way, the prompt will now change. You can install Sphinx with: |
---|
140 | |
---|
141 | $ pip install sphinx |
---|
142 | $ pip install sphinxcontrib-bibtex |
---|
143 | |
---|
144 | When you have finished you enter `deactivate`. |
---|
145 | |
---|
146 | Sphinx Per User Install |
---|
147 | ~~~~~~~~~~~~~~~~~~~~~~~ |
---|
148 | |
---|
149 | You can use this method to install a personal version of Sphinx if your host |
---|
150 | does not provide a suitable package: |
---|
151 | |
---|
152 | $ pip install -U --user sphinx |
---|
153 | $ pip install --user sphinxcontrib-bibtex |
---|
154 | |
---|
155 | On some hosts, this may complain that a newer version of pip is available. |
---|
156 | If so, then upgrade pip into your personal area. |
---|
157 | |
---|
158 | $ pip install --upgrade --user pip |
---|
159 | |
---|
160 | The personal area for these tools is ${HOME}/.local/bin. It should |
---|
161 | be PREPENDED to your path. On a 32-bit install of CentOS, RHEL, or |
---|
162 | Fedora, these were the PATH modifications to use the local install of |
---|
163 | Texlive and sphinx: |
---|
164 | |
---|
165 | export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH} |
---|
166 | export PATH=${HOME}/.local/bin:${PATH} |
---|
167 | |
---|
168 | If on a 64-bit install of CentOS, RHEL, or Fedora, these will |
---|
169 | be the PATH modifications to use the local install of Texlive |
---|
170 | and sphinx: |
---|
171 | |
---|
172 | export PATH=/usr/local/texlive/2016/bin/x86_64-linux/:${PATH} |
---|
173 | export PATH=${HOME}/.local/bin:${PATH} |
---|
174 | |
---|
175 | Windows |
---|
176 | ~~~~~~~ |
---|
177 | |
---|
178 | To build the documentation on Windows you need to install an offical Python |
---|
179 | build from https://www.python.org/. We suggest you install a recent 2.7 series |
---|
180 | 64bit build. The versions 2.7.9 and after include pip. |
---|
181 | |
---|
182 | Note: you cannot use the MSYS2 versions of Python because the pip libraries |
---|
183 | that contain C or C++ code are built with MSVC libraries and cannot integrate |
---|
184 | with the MSYS2 built python. |
---|
185 | |
---|
186 | The following assumes Python is installed to its default path of C:\Python27. |
---|
187 | |
---|
188 | Open an MSYS2 terminal window and add the needed paths to Python and its |
---|
189 | scripts: |
---|
190 | |
---|
191 | $ export PATH=/c/Python27/Scripts:/c/Python27:$PATH |
---|
192 | |
---|
193 | Install Sphinx and any needed extensions: |
---|
194 | |
---|
195 | $ pip install sphinx |
---|
196 | $ pip install sphinxcontrib-bibtex |
---|
197 | |
---|
198 | FreeBSD |
---|
199 | ~~~~~~~ |
---|
200 | |
---|
201 | PDF Quality: production |
---|
202 | |
---|
203 | Sphinx: |
---|
204 | |
---|
205 | # pkg install py27-sphinx |
---|
206 | |
---|
207 | PDF: |
---|
208 | |
---|
209 | # pkg install texlive-full |
---|
210 | |
---|
211 | Single HTML: |
---|
212 | |
---|
213 | # pkg install npm |
---|
214 | # npm install -g inliner |
---|
215 | |
---|
216 | Plant UML: |
---|
217 | |
---|
218 | Install NPM as shown in Single HTML then: |
---|
219 | |
---|
220 | # npm install -g node-plantuml |
---|
221 | |
---|
222 | Ditaa: |
---|
223 | |
---|
224 | # pkg install ditaa |
---|
225 | |
---|
226 | CentOS 7 |
---|
227 | ~~~~~~~~ |
---|
228 | |
---|
229 | PDF Quality: production |
---|
230 | |
---|
231 | Python 3: |
---|
232 | |
---|
233 | By default, CentOS 7 has Python 2.x. Luckily they now have Software |
---|
234 | Collections which lets you install and use a "collection" of newer |
---|
235 | software. As root, |
---|
236 | |
---|
237 | # yum install centos-release-scl |
---|
238 | # yum install rh-python36 |
---|
239 | |
---|
240 | Then you can create your own virtual Python environment |
---|
241 | for use with the Sphinx toolchain. |
---|
242 | |
---|
243 | $ cd ~ |
---|
244 | $ python -m venv rtemsdocs |
---|
245 | |
---|
246 | When you want to use the Sphinx toolchain. |
---|
247 | |
---|
248 | $ scl enable rh-python36 bash |
---|
249 | $ source ~/rtemsdocs/bin/activate |
---|
250 | |
---|
251 | Sphinx: |
---|
252 | |
---|
253 | $ pip install -U sphinx |
---|
254 | |
---|
255 | PDF: |
---|
256 | |
---|
257 | WARNING: Do NOT use the RPMs for texlive. They are incomplete and, in |
---|
258 | the best case, result in ugly PDFs. |
---|
259 | |
---|
260 | As root, install texlive per the instructions at |
---|
261 | http://tug.org/texlive/acquire-netinstall.html |
---|
262 | |
---|
263 | # wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz |
---|
264 | # tar xf install-tl-unx.tar.gz |
---|
265 | # cd install-tl-20161106 |
---|
266 | NOTE: The date in the name of the directory will change. |
---|
267 | # ./install-tl |
---|
268 | - Use the command line system. Select "O" for options if you want to |
---|
269 | change from A4 to US letter paper size by default. |
---|
270 | - Select "I" to install |
---|
271 | - The tools will be installed into a directory like the following: |
---|
272 | /usr/local/texlive/2016/bin/i386-linux/ |
---|
273 | |
---|
274 | NOTE: The year (2016) and host OS (i386-linux) will change to |
---|
275 | reflect 32 or 64 bit and OS name. |
---|
276 | |
---|
277 | You will also likely need to install the aspell RPM. |
---|
278 | |
---|
279 | Single HTML: |
---|
280 | |
---|
281 | NOTE: npm appears to be part of the EPEL repository for RHEL and CentOS. |
---|
282 | You may have to add that repository to your configuration. |
---|
283 | |
---|
284 | # yum install npm |
---|
285 | # npm install -g inliner |
---|
286 | |
---|
287 | Plant UML: |
---|
288 | |
---|
289 | Install NPM as shown in Single HTML then: |
---|
290 | |
---|
291 | # npm install -g node-plantuml |
---|
292 | |
---|
293 | Spell check: |
---|
294 | |
---|
295 | # yum install aspell |
---|
296 | |
---|
297 | PATH: |
---|
298 | |
---|
299 | Ensure the appropriate directories are PREPENDED to your PATH before |
---|
300 | building the documentation. Examples are shown below: |
---|
301 | |
---|
302 | export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH} |
---|
303 | export PATH=${HOME}/.local/bin:${PATH} |
---|
304 | |
---|
305 | CentOS 8 |
---|
306 | ~~~~~~~~ |
---|
307 | |
---|
308 | The steps for Centos 8 are similar to the steps for CentOS 7. |
---|
309 | There are just a couple differences. |
---|
310 | |
---|
311 | First, CentOS 8 uses Python 3.x as the default, so intalling the |
---|
312 | centos-release-scl and rh-python36 packages is unnecessary. |
---|
313 | Second, Centos 8 uses dnf as its package manager instead of yum, so |
---|
314 | packages such as npm should be installed using dnf instead. |
---|
315 | |
---|
316 | Arch Linux |
---|
317 | ~~~~~~~~~~ |
---|
318 | |
---|
319 | Sphinx: |
---|
320 | |
---|
321 | # pacman -S python-sphinx |
---|
322 | # pacman -S python-sphinxcontrib-bibtex |
---|
323 | |
---|
324 | PDF: |
---|
325 | |
---|
326 | # pacman -S texlive-bin texlive-core texlive-latexextra texlive-fontsextra |
---|
327 | |
---|
328 | openSUSE |
---|
329 | ~~~~~~~~ |
---|
330 | |
---|
331 | Packages: |
---|
332 | |
---|
333 | # zypper in python-pip 'texlive*' |
---|
334 | |
---|
335 | Sphinx: |
---|
336 | |
---|
337 | # pip install -U Sphinx |
---|
338 | |
---|
339 | Using pip to install Sphinx destroys the python-Sphinx package if installed via |
---|
340 | RPM. |
---|
341 | |
---|
342 | Latex Setup |
---|
343 | ~~~~~~~~~~~ |
---|
344 | |
---|
345 | Latex is used to create the PDF document. The setup of Latex varies from host |
---|
346 | to host operating system due to the way each host packages the texlive |
---|
347 | packages. There is no common naming and no real way to figure what texlive |
---|
348 | package is present in a host's packaging. It seems not all of texlive is |
---|
349 | available. |
---|
350 | |
---|
351 | The RTEMS Documentation waf configure phase checks for each texlive package used |
---|
352 | in the generated output and the styles. If you complete configure with the |
---|
353 | --pdf option you should be able to build PDF documentation. |
---|
354 | |
---|
355 | The texlive package requirements come from the Latex styles we are using and |
---|
356 | Sphinx. |
---|
357 | |
---|
358 | An example of failures are: |
---|
359 | |
---|
360 | Checking for Tex package 'Bjarne' : ok |
---|
361 | Checking for Tex package 'alltt' : ok |
---|
362 | Checking for Tex package 'amsmath' : ok |
---|
363 | Checking for Tex package 'amssymb' : ok |
---|
364 | Checking for Tex package 'amstext' : ok |
---|
365 | Checking for Tex package 'array' : ok |
---|
366 | Checking for Tex package 'atbegshi' : ok |
---|
367 | Checking for Tex package 'babel' : ok |
---|
368 | Checking for Tex package 'calc' : ok |
---|
369 | Checking for Tex package 'capt-of' : not found (please install) |
---|
370 | Checking for Tex package 'charter' : ok |
---|
371 | Checking for Tex package 'cmap' : ok |
---|
372 | Checking for Tex package 'color' : ok |
---|
373 | Checking for Tex package 'eqparbox' : not found (please install) |
---|
374 | Checking for Tex package 'etoolbox' : ok |
---|
375 | Checking for Tex package 'fancybox' : ok |
---|
376 | Checking for Tex package 'fancyhdr' : ok |
---|
377 | Checking for Tex package 'fancyvrb' : ok |
---|
378 | Checking for Tex package 'float' : ok |
---|
379 | Checking for Tex package 'fncychap' : ok |
---|
380 | Checking for Tex package 'fontenc' : ok |
---|
381 | Checking for Tex package 'footnote' : ok |
---|
382 | Checking for Tex package 'framed' : ok |
---|
383 | Checking for Tex package 'graphicx' : ok |
---|
384 | Checking for Tex package 'hypcap' : ok |
---|
385 | Checking for Tex package 'hyperref' : ok |
---|
386 | Checking for Tex package 'ifplatform' : not found (please install) |
---|
387 | Checking for Tex package 'ifthen' : ok |
---|
388 | Checking for Tex package 'inconsolata' : not found (please install) |
---|
389 | Checking for Tex package 'inputenc' : ok |
---|
390 | Checking for Tex package 'keyval' : ok |
---|
391 | Checking for Tex package 'kvoptions' : ok |
---|
392 | Checking for Tex package 'lato' : not found (please install) |
---|
393 | Checking for Tex package 'lineno' : ok |
---|
394 | Checking for Tex package 'longtable' : ok |
---|
395 | Checking for Tex package 'makeidx' : ok |
---|
396 | Checking for Tex package 'multirow' : ok |
---|
397 | Checking for Tex package 'parskip' : ok |
---|
398 | Checking for Tex package 'pdftexcmds' : ok |
---|
399 | Checking for Tex package 'textcomp' : ok |
---|
400 | Checking for Tex package 'threeparttable' : ok |
---|
401 | Checking for Tex package 'times' : ok |
---|
402 | Checking for Tex package 'titlesec' : ok |
---|
403 | Checking for Tex package 'upquote' : not found (please install) |
---|
404 | Checking for Tex package 'utf8' : ok |
---|
405 | Checking for Tex package 'wrapfig' : ok |
---|
406 | Checking for Tex package 'xcolor' : ok |
---|
407 | Checking for Tex package 'xstring' : ok |
---|
408 | There are 6 Tex package failures. Please fix. |
---|
409 | |
---|
410 | If you find there is an issue please post the developers list. |
---|
411 | |
---|
412 | Building |
---|
413 | -------- |
---|
414 | |
---|
415 | Note: waf-1.9.5 is a little noisy when running tex builds and tests. I hope |
---|
416 | to have this resolved soon. |
---|
417 | |
---|
418 | To build enter in the top directory: |
---|
419 | |
---|
420 | $ ./waf configure [--pdf] [--singlehtml] [--prefix] \ |
---|
421 | [--sphinx-options] \ |
---|
422 | [--sphinx-nit-pick] \ |
---|
423 | [--plantuml] \ |
---|
424 | [--ditaa] \ |
---|
425 | [--disable-extra-fonts] |
---|
426 | |
---|
427 | $ ./waf |
---|
428 | |
---|
429 | The '--pdf' and '--singlehtml' options can be added to configure to build those |
---|
430 | output formats. |
---|
431 | |
---|
432 | Sphinx options can be added using the `--sphinx-options` option. If you have |
---|
433 | more than option use a quoted argument. This is an advanced feature that can |
---|
434 | be useful when experimenting with the `sphinx-build` command. |
---|
435 | |
---|
436 | Sphinx nit-picky mode adds `-n` to the `sphinx-build` command line to generate |
---|
437 | warnings and extra information about the source to help make sure our |
---|
438 | documentation source is as clean as possible. Please use this when writing |
---|
439 | documentation or making updates. |
---|
440 | |
---|
441 | The '--disable-extra-fonts' allows you to build PDF documents with out the |
---|
442 | fonts we use for a better quality document. Use this option to build without |
---|
443 | needing the extra fonts accepting you will get poor quality documents. |
---|
444 | |
---|
445 | To build and install to a specific location: |
---|
446 | |
---|
447 | $ ./waf configure --prefix=/foo/my/location |
---|
448 | $ ./waf build install |
---|
449 | |
---|
450 | To build the PlantUML and Ditaa images: |
---|
451 | |
---|
452 | $ ./waf configure --plantuml --ditaa |
---|
453 | $ ./waf clean build |
---|
454 | |
---|
455 | To nit-pick the source use: |
---|
456 | |
---|
457 | $ ./waf configure --sphinx-nit-pick |
---|
458 | $ ./waf clean build |
---|
459 | |
---|
460 | If you need to debug what is happening use configure with a suitable Sphinx |
---|
461 | verbose level: |
---|
462 | |
---|
463 | $ ./waf configure --sphinx-options "-V -V" |
---|
464 | $ ./waf clean build |
---|
465 | |
---|
466 | You can enter a manual's directory and run the same configure command and build |
---|
467 | just that manual. |
---|
468 | |
---|
469 | Documentation Standard |
---|
470 | ---------------------- |
---|
471 | |
---|
472 | This following details the documentation standard. If in doubt first search the |
---|
473 | existing documentation for an example and if unsure ask. |
---|
474 | |
---|
475 | 1. All text is to be formatted to wrap at 80 columns. Do not manually line feed |
---|
476 | before 80. |
---|
477 | |
---|
478 | 2. Do not insert tab characters, use spaces, no trailing white space. |
---|
479 | |
---|
480 | 3. Pasted text such as console output can exceed 80 columns; however, it is |
---|
481 | preferred even this text is wrapped at 80 columns. Long lines in code block |
---|
482 | text causes issues with the PDF output. |
---|
483 | |
---|
484 | 4. The headings use the following: |
---|
485 | |
---|
486 | Heading Description |
---|
487 | 1 ###### Part |
---|
488 | 2 ****** Section |
---|
489 | 3 ====== Sub-section |
---|
490 | 4 ------ Sub-sub-section |
---|
491 | 5 ^^^^^^ Sub-sub-sub-section |
---|
492 | 6 ~~~~~~ Sub-sub-sub-sub-section |
---|
493 | |
---|
494 | 5. For literal output such as shell commands and code, do not use '::' |
---|
495 | at the trailing edge of the previous paragraph as it generates |
---|
496 | warnings as the autodetect fails to find a suitable format. Use the |
---|
497 | '.. code-block::' with a suitable lexical label. The lexers are: |
---|
498 | |
---|
499 | http://pygments.org/docs/lexers/ |
---|
500 | |
---|
501 | Use the short names. For C code use 'c' code and 'shell' for shell |
---|
502 | scripts and for terminal output use 'none'. If you need line |
---|
503 | numbers use: |
---|
504 | |
---|
505 | .. code-block:: shell |
---|
506 | :linenos: |
---|
507 | |
---|
508 | We support two forms of commands and outputs. |
---|
509 | |
---|
510 | The first is to have a shell command block with just the commands |
---|
511 | and if required an output block with the output or some of the |
---|
512 | output. Use 'none' for the output block. Make sure the text clearly |
---|
513 | states the block is the output, if it has been edited to shorten |
---|
514 | the amount of output and if there are any special operating modes, |
---|
515 | for example needing to be 'root'. |
---|
516 | |
---|
517 | The second is to use a single block of type 'none' with the command |
---|
518 | and output together as seen in a terminal session. The commands are |
---|
519 | identifed by the standard shell prompt characters where '$' is a |
---|
520 | user prompt and '#' is a 'root' prompt. |
---|
521 | |
---|
522 | Do not embed the version or version major number in the literal |
---|
523 | commands or examples. Use the replacements listed in 10. |
---|
524 | |
---|
525 | 6. Use the directives for 'note', 'warning', and 'topic'. Do not add 'TIP', |
---|
526 | 'Important' or 'Warning' to the text. Let the mark-up language handle |
---|
527 | this. The supported directives are: |
---|
528 | |
---|
529 | .. warning:: |
---|
530 | .. note:: |
---|
531 | .. topic:: |
---|
532 | |
---|
533 | These directives reference specific CSS style support. |
---|
534 | |
---|
535 | 7. Images are placed in the 'images' directory. Do not place images in the |
---|
536 | source directories. Using a common 'images' tree of images promotes sharing |
---|
537 | of images. To add an image use: |
---|
538 | |
---|
539 | .. figure:: ../images/my-image.png |
---|
540 | :wdith: 75% |
---|
541 | :align: center |
---|
542 | :alt: This is the alt text for some output types. |
---|
543 | |
---|
544 | 8. Callouts can be implemented manually using a literal block ('::') |
---|
545 | or a code block. Either way, a topic block is used for the items. For |
---|
546 | example: |
---|
547 | |
---|
548 | .. code-block: c |
---|
549 | |
---|
550 | #include <stdio.h> <1> |
---|
551 | int main(int argc, char** argv) <2> |
---|
552 | { |
---|
553 | printf("Hello world\n"); <3> |
---|
554 | return 0; <4> |
---|
555 | } |
---|
556 | |
---|
557 | .. topic:: Items: |
---|
558 | |
---|
559 | 1. Include the standard input/output header file. |
---|
560 | |
---|
561 | 2. The program starts here. |
---|
562 | |
---|
563 | 3. Print something to the standard output device. |
---|
564 | |
---|
565 | 4. Exit with an exit code of 0. This value can be checked by the |
---|
566 | caller of this program. |
---|
567 | |
---|
568 | Note the topic items are manually numbered, which makes it easier to see |
---|
569 | which item matches the text. Use <> for the number and align at a position |
---|
570 | that makes the number as visible as possible. Use hanging indents |
---|
571 | if an items extends past a single line. |
---|
572 | |
---|
573 | 9. Use the RTEMS domain references for URLs and mailing lists. For example to |
---|
574 | insert the RTEMS developers list use: |
---|
575 | |
---|
576 | :r:list:`devel` |
---|
577 | :r:url:`git` |
---|
578 | |
---|
579 | The valid lists are: |
---|
580 | |
---|
581 | announce : Announce Mailing List |
---|
582 | bugs : Bugs Mailing List |
---|
583 | devel : Developers Mailing List |
---|
584 | build : Build Logs |
---|
585 | users : Users Mailing List |
---|
586 | vc : Version Control Mailing List |
---|
587 | |
---|
588 | The valid URLs are: |
---|
589 | |
---|
590 | trac : https://devel.rtems.org/ |
---|
591 | devel : https://devel.rtems.org/ |
---|
592 | www : https://www.rtems.org/ |
---|
593 | buildbot : https://buildbot.rtems.org/ |
---|
594 | builder : https://builder.rtems.org/ |
---|
595 | docs : https://docs.rtems.org/ |
---|
596 | lists : https://lists.rtems.org/ |
---|
597 | git : https://git.rtems.org/ |
---|
598 | ftp : https://ftp.rtems.org/ |
---|
599 | review : https://review.rtems.org/ |
---|
600 | bugs : https://devel.rtems.org/wiki/Bugs/ |
---|
601 | gsoc : https://devel.rtems.org/wiki/GSoC/ |
---|
602 | socis : https://devel.rtems.org/wiki/SOCIS/ |
---|
603 | |
---|
604 | 10. Use the following to embed the version number in any part of the |
---|
605 | documentation source: |
---|
606 | |
---|
607 | 1. @rtems-version@ |
---|
608 | |
---|
609 | The complete version string of the documentation. |
---|
610 | |
---|
611 | 2. @rtems-ver-major@ |
---|
612 | |
---|
613 | The version major number. |
---|
614 | |
---|
615 | 2. @rtems-ver-minor@ |
---|
616 | |
---|
617 | The version minor number. |
---|
618 | |
---|
619 | 2. @rtems-ver-revision@ |
---|
620 | |
---|
621 | The version revision number. |
---|
622 | |
---|
623 | The replacement happens during the source read phase of the build |
---|
624 | and is not context specific. The subsituation will happen in code |
---|
625 | blocks and other normally quoated area. |
---|
626 | |
---|
627 | It is a requirement these be used then embedded commands or |
---|
628 | related text in the documentation to let the documentatoin track |
---|
629 | the release. For example `microblaze-rtems6-gdb` should be written |
---|
630 | as `microblaze-rtems@rtems-ver-major@-gdb`. |
---|