source: rtems-docs/README.txt @ 2e6f49f

5
Last change on this file since 2e6f49f was 2e6f49f, checked in by Chris Johns <chrisj@…>, on 02/21/19 at 02:03:07

Add a cheetsheet link to the README.txt

  • Property mode set to 100644
File size: 16.0 KB
Line 
1RTEMS Project Documentation
2===========================
3
4The documents are written in ReST and built using Sphinx. The build system will
5check the version of Sphinx and ensure you have a suitable version
6available. If your host does not provide a packaged version use PIP to fetch a
7recent version. The Sphinx website provides details on doing this.
8
9ReST is the Re-Structured-Text format. It is a simple markup language that allows
10us to create quality documentaion. It is flexible and powerful however does not
11attempt to train it to create a specific format. You need to test any new way
12of presenting something on all output formats. What may look great in one
13format may not translate with the same clarity to another output format.
14
15The 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
21The PDF format is created using Latex and that uses texlive packages. This
22exposes us to the complex world of Latex however the quality of the documents
23created is worth it.
24
25Images can be created from source using PlantUML and Ditaa.
26
27A Sphinx checksheet is:
28
29 http://docs.sphinxdocs.com/en/latest/cheatsheet.html#rst-cheat-sheet
30
31Production Quality Hosts
32------------------------
33
34We allow the building of PDF documentation on hosts that do not have a fully
35suitable texlive environment and this results in quality that is not at the
36production level.
37
38The hosts which produce production quality are:
39
40 FreeBSD
41 CentOS 6 and 7 (if using texlive, not RPMs of texlive)
42
43NOTE: RedHat Enterprise Linux (RHEL) and Fedora should be the same as CentOS.
44
45Images
46------
47
48All images should be placed int he 'images' directory and referenced from the
49ReST with a relative path. This lets us shared and control images.
50
51We prefer being able to build images from source. This is not always possible
52so SVG format is preferred with generated PNG images to make sure the quality
53is consistent when building PDF output.
54
55Building images requires the source with an apporoiate file extension
56is placed in the images directory. The built output image is written
57back to the images directory. All images may be built or rebuilt when
58building images is enabled via the waf configure command line. Please
59only add and commit those images that have changed.
60
61We support building images in:
62
631. PlantUML (.puml), enable with `--plantuml`
64
652. Ditaa (.ditaa), enable with `--ditaa`
66
67We support the PlantUML image language. The PlantUML home page is:
68
69 http://plantuml.com/
70
71The page as a link to an 'online demo server' you can use to create images
72rathre than installing PlantUML. Save you source then View and save the PNG
73format image. The PlantUML language reference guide is:
74
75 http://plantuml.com/PlantUML_Language_Reference_Guide.pdf
76
77And the web site has online documentation. The image source extension is
78'.puml'.
79
80We also support Ditaa image language. The Ditaa home page is:
81
82 http://ditaa.sourceforge.net/
83
84The home page contain the language options. The PlantUML online demo server
85supports Ditaa so use that resource as an online tool. The Ditaa image source
86extension is '.ditaa'.
87
88You do not need PlantUML or Ditaa install to build our documentation. The
89online resources can be used. Save the source and the generated PNG file in the
90same directory under 'images'.
91
92Host Setup
93----------
94
95HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install,
96and building a Single HTML page requires the 'inliner' tool. The
97sphinxcontrib-bibtex extension is mandatory. PlantUML requres the Node.js
98package called 'node-plantuml' which installs the 'puml' command and Ditaa needs
99the 'ditaa' command and package. Ditaa images are built using the 'puml'
100command.
101
102Please add your host as you set it up.
103
104Sphinx Per User Install
105~~~~~~~~~~~~~~~~~~~~~~~
106
107You can use this method to install a personal version of Sphinx if your host
108does not provide a suitable package:
109
110  $ pip install -U --user sphinx
111  $ pip install --user sphinxcontrib-bibtex
112
113On some hosts, this may complain that a newer version of pip is available.
114If so, then upgrade pip into your personal area.
115
116 $ pip install --upgrade --user pip
117
118The personal area for these tools is ${HOME}/.local/bin. It should
119be PREPENDED to your path. On a 32-bit install of CentOS, RHEL, or
120Fedora, these were the PATH modifications to use the local install of
121Texlive and sphinx:
122
123  export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH}
124  export PATH=${HOME}/.local/bin:${PATH}
125
126If on a 64-bit install of CentOS, RHEL, or Fedora, these will
127be the PATH modifications to use the local install of Texlive
128and sphinx:
129
130  export PATH=/usr/local/texlive/2016/bin/x86_64-linux/:${PATH}
131  export PATH=${HOME}/.local/bin:${PATH}
132
133Windows
134~~~~~~~
135
136To build the documentation on Windows you need to install an offical Python
137build from https://www.python.org/. We suggest you install a recent 2.7 series
13864bit build. The versions 2.7.9 and after include pip.
139
140Note: you cannot use the MSYS2 versions of Python because the pip libraries
141that contain C or C++ code are built with MSVC libraries and cannot integrate
142with the MSYS2 built python.
143
144The following assumes Python is installed to its default path of C:\Python27.
145
146Open an MSYS2 terminal window and add the needed paths to Python and its
147scripts:
148
149 $ export PATH=/c/Python27/Scripts:/c/Python27:$PATH
150
151Install Sphinx and any needed extensions:
152
153 $ pip install sphinx
154 $ pip install sphinxcontrib-bibtex
155
156FreeBSD
157~~~~~~~
158
159PDF Quality: production
160
161Sphinx:
162
163  # pkg install py27-sphinx
164
165PDF:
166
167  # pkg install texlive-full
168
169Single HTML:
170
171  # pkg install npm
172  # npm install -g inliner
173
174Plant UML:
175
176Install NPM as shown in Single HTML then:
177
178  # npm install -g node-plantuml
179
180Ditaa:
181
182  # pkg install ditaa
183
184CentOS 6 and 7
185~~~~~~~~~~~~~~
186
187PDF Quality: production
188
189Sphinx:
190
191  $ pip install -U sphinx
192
193PDF:
194
195  WARNING: Do NOT use the RPMs for texlive. They are incomplete and, in
196           the best case, result in ugly PDFs.
197
198  As root, install texlive per the instructions at
199  http://tug.org/texlive/acquire-netinstall.html
200
201  # wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
202  # tar xf install-tl-unx.tar.gz
203  # cd install-tl-20161106
204    NOTE: The date in the name of the directory will change.
205  # ./install-tl
206    - Use the command line system. Select "O" for options if you want to
207      change from A4 to US letter paper size by default.
208    - Select "I" to install
209    - The tools will be installed into a directory like the following:
210      /usr/local/texlive/2016/bin/i386-linux/
211
212     NOTE: The year (2016) and host OS (i386-linux) will change to
213           reflect 32 or 64 bit and OS name.
214
215Single HTML:
216
217NOTE: npm appears to be part of the EPEL repository for RHEL and CentOS.
218You may have to add that repository to your configuration.
219
220  # yum install npm
221  # npm install -g inliner
222
223Plant UML:
224
225Install NPM as shown in Single HTML then:
226
227  # npm install -g node-plantuml
228
229Spell check:
230
231  # yum install aspell
232
233PATH:
234
235  Ensure the appropriate directories are PREPENDED to your PATH before
236  building the documentation. Examples are shown below:
237
238  export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH}
239  export PATH=${HOME}/.local/bin:${PATH}
240
241Arch Linux
242~~~~~~~~~~
243
244Sphinx:
245
246  # pacman -S python-sphinx
247
248PDF:
249
250  # pacman -S texlive-bin texlive-core texlive-latexextra texlive-fontsextra \
251
252openSUSE
253~~~~~~~~
254
255Packages:
256
257  # zypper in python-pip 'texlive*'
258
259Sphinx:
260
261  # pip install -U Sphinx
262
263Using pip to install Sphinx destroys the python-Sphinx package if installed via
264RPM.
265
266Latex Setup
267~~~~~~~~~~~
268
269Latex is used to create the PDF document.  The setup of Latex varies from host
270to host operating system due to the way each host packages the texlive
271packages. There is no common naming and no real way to figure what texlive
272package is present in a host's packaging. It seems not all of texlive is
273available.
274
275The RTEMS Documentation waf configure phase check for each texlive package used
276in the generated output and the styles. If you complete configure with the
277--pdf option you should be able to build PDF documentation.
278
279The texlive package requirments come from the Latex styles we are using and
280Sphinx.
281
282An example of failures are:
283
284  Checking for Tex package 'Bjarne'        : ok
285  Checking for Tex package 'alltt'         : ok
286  Checking for Tex package 'amsmath'       : ok
287  Checking for Tex package 'amssymb'       : ok
288  Checking for Tex package 'amstext'       : ok
289  Checking for Tex package 'array'         : ok
290  Checking for Tex package 'atbegshi'      : ok
291  Checking for Tex package 'babel'         : ok
292  Checking for Tex package 'calc'          : ok
293  Checking for Tex package 'capt-of'       : not found (please install)
294  Checking for Tex package 'charter'       : ok
295  Checking for Tex package 'cmap'          : ok
296  Checking for Tex package 'color'         : ok
297  Checking for Tex package 'eqparbox'      : not found (please install)
298  Checking for Tex package 'etoolbox'      : ok
299  Checking for Tex package 'fancybox'      : ok
300  Checking for Tex package 'fancyhdr'      : ok
301  Checking for Tex package 'fancyvrb'      : ok
302  Checking for Tex package 'float'         : ok
303  Checking for Tex package 'fncychap'      : ok
304  Checking for Tex package 'fontenc'       : ok
305  Checking for Tex package 'footnote'      : ok
306  Checking for Tex package 'framed'        : ok
307  Checking for Tex package 'graphicx'      : ok
308  Checking for Tex package 'hypcap'        : ok
309  Checking for Tex package 'hyperref'      : ok
310  Checking for Tex package 'ifplatform'    : not found (please install)
311  Checking for Tex package 'ifthen'        : ok
312  Checking for Tex package 'inconsolata'   : not found (please install)
313  Checking for Tex package 'inputenc'      : ok
314  Checking for Tex package 'keyval'        : ok
315  Checking for Tex package 'kvoptions'     : ok
316  Checking for Tex package 'lato'          : not found (please install)
317  Checking for Tex package 'lineno'        : ok
318  Checking for Tex package 'longtable'     : ok
319  Checking for Tex package 'makeidx'       : ok
320  Checking for Tex package 'multirow'      : ok
321  Checking for Tex package 'parskip'       : ok
322  Checking for Tex package 'pdftexcmds'    : ok
323  Checking for Tex package 'textcomp'      : ok
324  Checking for Tex package 'threeparttable' : ok
325  Checking for Tex package 'times'          : ok
326  Checking for Tex package 'titlesec'       : ok
327  Checking for Tex package 'upquote'        : not found (please install)
328  Checking for Tex package 'utf8'           : ok
329  Checking for Tex package 'wrapfig'        : ok
330  Checking for Tex package 'xcolor'         : ok
331  Checking for Tex package 'xstring'        : ok
332  There are 6 Tex package failures. Please fix.
333
334If you find there is an issue please post the developers list.
335
336Building
337--------
338
339Note: waf-1.9.5 is a little noisy when running tex builds and tests. I hope
340      to have this resolved soon.
341
342To build enter in the top directory:
343
344  $ ./waf configure [--pdf] [--singlehtml] [--prefix] \
345                    [--sphinx-options] \
346                    [--sphinx-nit-pick] \
347                    [--plantuml] \
348                    [--ditaa] \
349                    [--disable-extra-fonts]
350
351  $ ./waf
352
353The '--pdf' and '--singlehtml' options can be added to configure to build those
354output formats.
355
356Sphinx options can be added using the `--sphinx-options` option. If you have
357more than option use a quoted argument. This is an advanced feature that can
358be useful when experimenting with the `sphinx-build` command.
359
360Sphinx nit-picky mode adds `-n` to the `sphinx-build` command line to generate
361warnings and extra information about the source to help make sure our
362documentation source is as clean as possible. Please use this when writing
363documentation or making updates.
364
365The '--disable-extra-fonts' allows you to build PDF documents with out the
366fonts we use for a better quality document. Use this option to build without
367needing the extra fonts accepting you will get poor quality documents.
368
369To build and install to a specific location:
370
371  $ ./waf configure --prefix=/foo/my/location
372  $ ./waf build install
373
374To build the PlantUML and Ditaa images:
375
376  $ ./waf configure --plantuml --ditaa
377  $ ./waf clean build
378
379To nit-pick the source use:
380
381  $ ./waf configure --sphinx-nit-pick
382  $ ./waf clean build
383
384If you need to debug what is happening use configure with a suitable Sphinx
385verbose level:
386
387  $ ./waf configure --sphinx-options "-V -V"
388  $ ./waf clean build
389
390You can enter a manual's directory and run the same configure command and build
391just that manual.
392
393Documentation Standard
394----------------------
395
396This following details the documentation standard. If in doubt first search the
397existing documentation for an example and if unsure ask.
398
3991. All text is to be formatted to wrap at 80 columns. Do not manually line feed
400   before 80.
401
4022. Do not insert tab characters, use spaces, no trailing white space.
403
4043. Pasted text such as console output can exceed 80 columns however it is
405   preferred even this text is wrapped at 80 columns. Long lines in code block
406   text causes issues with the PDF output.
407
4084. The headings use the following:
409
410      Heading   Description
411      1  ###### Part
412      2  ****** Section
413      3  ====== Sub-section
414      4  ------ Sub-sub-section
415      5  ^^^^^^ Sub-sub-sub-section
416      6  ~~~~~~ Sub-sub-sub-sub-section
417
4185. For literal output, such as shell commands and code use '::' at the trailing
419   edge of the previous paragraph. Use the '.. code-block::' with
420   'c' for C code and 'shell' for shell code and terminal output. If you need
421   line number use:
422
423    .. code-block:: shell
424       :linenos:
425
4266. Use the directives for 'note', 'warning', and 'topic'. Do not add 'TIP',
427   'Important' or 'Warning' to the text. Let the mark-up language handle
428   this. The supported directives are:
429
430     .. warning::
431     .. note::
432     .. topic::
433
434   These directives reference specific CSS style support.
435
4367. Images are placed in the 'images' directory. Do not place images in the
437   source directories. Using a common 'images' tree of images promotes sharing
438   of images. To add an image use:
439
440    .. figure:: ../images/my-image.png
441       :wdith: 75%
442       :align: center
443       :alt: This is the alt text for some output types.
444
4458. Callouts can be implemented manually using a literal block which can use
446   '::' or a code block and topic block is used for the items. For
447   example:
448
449     .. code-block: c
450
451        #include <stdio.h>  <1>
452        int main(int argc, char** argv)  <2>
453        {
454           printf("Hello world\n");  <3>
455           return 0;   <4>
456        }
457
458     .. topic:: Items:
459
460       1. Include the standard input/output header file.
461
462       2. The program starts here.
463
464       3. Print something to the standard output device.
465
466       4. Exit with an exit code of 0. This value can be checked by the
467          caller of this program.
468
469   Note, the topic items are manually numbered, which makes it easier to see
470   which item matches the text. Use <> for the number and align at a position
471   that works and makes the number as visible as possible. Use hanging indents
472   if an items extends past a single line.
473
4749. Use the RTEMS domain references for URLs and mailing lists. For example to
475   insert the RTEMS developers list use:
476
477     :r:list:`devel`
478     :r:url:`git`
479
480   The valid lists are:
481
482     announce     : Announce Mailing List
483     bugs         : Bugs Mailing List
484     devel        : Developers Mailing List
485     build        : Build Logs
486     users        : Users Mailing List
487     vc           : Version Control Mailing List
488
489  The valid URLs are:
490
491     trac         : https://devel.rtems.org/
492     devel        : https://devel.rtems.org/
493     www          : https://www.rtems.org/
494     buildbot     : https://buildbot.rtems.org/
495     builder      : https://builder.rtems.org/
496     docs         : https://docs.rtems.org/
497     lists        : https://lists.rtems.org/
498     git          : https://git.rtems.org/
499     ftp          : https://ftp.rtems.org/
500     review       : https://review.rtems.org/
501     bugs         : https://devel.rtems.org/wiki/Bugs/
502     gsoc         : https://devel.rtems.org/wiki/GSoC/
503     socis        : https://devel.rtems.org/wiki/SOCIS/
Note: See TracBrowser for help on using the repository browser.