diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 191 |
1 files changed, 159 insertions, 32 deletions
@@ -1,16 +1,17 @@ RTEMS Project Documentation =========================== -The documents are written in ReST and built using Sphinx. The build system will -check the version of Sphinx and ensure you have a suitable version -available. If your host does not provide a packaged version use PIP to fetch a +The documents are written in ReST and built using Sphinx. The waf build system +will check the version of Sphinx and ensure you have a suitable version +available. If your host does not provide a packaged version, use PIP to fetch a recent version. The Sphinx website provides details on doing this. -ReST is the Re-Structured-Text format. It is a simple markup language that allows -us to create quality documentaion. It is flexible and powerful however does not -attempt to train it to create a specific format. You need to test any new way -of presenting something on all output formats. What may look great in one -format may not translate with the same clarity to another output format. +ReST is the Re-Structured-Text format. It is a simple markup language that +allows us to create quality documentation which can easily be converted to +multiple different formats. This flexibility is convenient, but you still need +to test any new way of presenting something on all output formats. What may look +great in one format may not translate with the same clarity to another output +format. The RTEMS Documentation output formats are: @@ -26,7 +27,7 @@ Images can be created from source using PlantUML and Ditaa. A Sphinx checksheet is: - http://docs.sphinxdocs.com/en/latest/cheatsheet.html#rst-cheat-sheet + https://sphinx-tutorial.readthedocs.io/cheatsheet/#rst-cheat-sheet Production Quality Hosts ------------------------ @@ -45,14 +46,14 @@ NOTE: RedHat Enterprise Linux (RHEL) and Fedora should be the same as CentOS. Images ------ -All images should be placed int he 'images' directory and referenced from the -ReST with a relative path. This lets us shared and control images. +All images should be placed in the 'images' directory and referenced from the +ReST with a relative path. This lets us share and control images. We prefer being able to build images from source. This is not always possible so SVG format is preferred with generated PNG images to make sure the quality is consistent when building PDF output. -Building images requires the source with an apporoiate file extension +Building images requires the source with an appropriate file extension is placed in the images directory. The built output image is written back to the images directory. All images may be built or rebuilt when building images is enabled via the waf configure command line. Please @@ -69,7 +70,7 @@ We support the PlantUML image language. The PlantUML home page is: http://plantuml.com/ The page as a link to an 'online demo server' you can use to create images -rathre than installing PlantUML. Save you source then View and save the PNG +rather than installing PlantUML. Save you source then View and save the PNG format image. The PlantUML language reference guide is: http://plantuml.com/PlantUML_Language_Reference_Guide.pdf @@ -81,25 +82,104 @@ We also support Ditaa image language. The Ditaa home page is: http://ditaa.sourceforge.net/ -The home page contain the language options. The PlantUML online demo server +The home page contains the language options. The PlantUML online demo server supports Ditaa so use that resource as an online tool. The Ditaa image source extension is '.ditaa'. -You do not need PlantUML or Ditaa install to build our documentation. The +You do not need PlantUML or Ditaa installed to build our documentation. The online resources can be used. Save the source and the generated PNG file in the same directory under 'images'. +*Note:* +Please consider using PlantUML and Ditaa before other tools because we +can generate the images from source automatically and it gives the +documentation a similar look and feel. Other options may be considered +if the image cannot be easily created by PlantUML or Ditaa but please +ask before starting down that path because it may not be accepted. + +Image editing tools tend to have a specific look and feel and this +characterizes the images they create. Altering an image often means +the original tool is required. An open output format allows us to +integrate the image into the document however we are then required to +monitor and maintain that tool if we need to make changes. The fewer +alternatives we have to maintain the easier it is for the project over +a long period of time. + Host Setup ---------- HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install, and building a Single HTML page requires the 'inliner' tool. The -sphinxcontrib-bibtex extension is mandatory. PlantUML requres the Node.js +sphinxcontrib-bibtex extension is mandatory. PlantUML requires the Node.js package called 'node-plantuml' which installs the 'puml' command and Ditaa needs the 'ditaa' command and package. Ditaa images are built using the 'puml' command. -Please add your host as you set it up. +Please add your host to this section as you set it up. + +The best results are produced with Python3 and a virtual environment`. It can +create a specific python environment using `pip`. + +Similarly, npm packages can be installed into a users $HOME directory. + +Versions +~~~~~~~~ + + Sphinx 7.2.6 + sphinx-rtd-theme 2.0.0 + sphinxcontrib-applehelp 1.0.7 + sphinxcontrib-bibtex 2.6.1 + sphinxcontrib-devhelp 1.0.5 + sphinxcontrib-htmlhelp 2.0.4 + sphinxcontrib-jquery 4.1 + sphinxcontrib-jsmath 1.0.1 + sphinxcontrib-qthelp 1.0.6 + sphinxcontrib-serializinghtml 1.1.9 + + +Python Virtual Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The project recommends virtual environments for building RTEMS +documentation using Sphinx. A virtual envionment lets you install and +maintain a Sphinx build environment without installing and depending +on system wide packages. + +Create a directory to house the virtual environment, create the environment, +and then activate it. This example assumes Python3 and the `venv` module: + + $ mkdir sphinx + $ python3 -m venv sphinx + $ . ./sphinx/bin/activate + +Alternatively you can use the `virtualenv` command: + + $ mkdir sphinx + $ virtualenv sphinx + $ . ./sphinx/bin/activate + +Either way, the prompt will now change. You can install Sphinx with: + + $ pip install sphinx + $ pip install sphinxcontrib-bibtex + $ pip install sphinxcontrib-jquery + $ pip install sphinx-rtd-theme + +When you have finished using sphinx and buildind documentation you +enter `deactivate`. + +NPM Per User Environment +~~~~~~~~~~~~~~~~~~~~~~~~ + +Change npm's default directory to a local one: + + mkdir ~/.npm-global + npm config set prefix '~/.npm-global' + +Subsequent packages installed via `npm install` will be local +to the user. The following shows the PATH changes needed. + + export PATH=${HOME}/.npm-global/bin:$PATH Sphinx Per User Install ~~~~~~~~~~~~~~~~~~~~~~~ @@ -109,6 +189,8 @@ does not provide a suitable package: $ pip install -U --user sphinx $ pip install --user sphinxcontrib-bibtex + $ pip install --user sphinxcontrib-jquery + $ pip install --user sphinx-rtd-theme On some hosts, this may complain that a newer version of pip is available. If so, then upgrade pip into your personal area. @@ -133,7 +215,7 @@ and sphinx: Windows ~~~~~~~ -To build the documentation on Windows you need to install an offical Python +To build the documentation on Windows you need to install an official Python build from https://www.python.org/. We suggest you install a recent 2.7 series 64bit build. The versions 2.7.9 and after include pip. @@ -152,6 +234,8 @@ Install Sphinx and any needed extensions: $ pip install sphinx $ pip install sphinxcontrib-bibtex + $ pip install sphinxcontrib-jquery + $ pip install sphinx-rtd-theme FreeBSD ~~~~~~~ @@ -160,7 +244,7 @@ PDF Quality: production Sphinx: - # pkg install py27-sphinx + Use a virtual environment and pip. PDF: @@ -190,7 +274,7 @@ Python 3: By default, CentOS 7 has Python 2.x. Luckily they now have Software Collections which lets you install and use a "collection" of newer -software. As root, +software. As root, # yum install centos-release-scl # yum install rh-python36 @@ -260,12 +344,24 @@ PATH: export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH} export PATH=${HOME}/.local/bin:${PATH} +CentOS 8 +~~~~~~~~ + +The steps for Centos 8 are similar to the steps for CentOS 7. +There are just a couple differences. + +First, CentOS 8 uses Python 3.x as the default, so installing the +centos-release-scl and rh-python36 packages are unnecessary. +Second, Centos 8 uses dnf as its package manager instead of yum, so +packages such as npm should be installed using dnf instead. + Arch Linux ~~~~~~~~~~ Sphinx: # pacman -S python-sphinx + # pacman -S python-sphinxcontrib-bibtex PDF: @@ -294,11 +390,11 @@ packages. There is no common naming and no real way to figure what texlive package is present in a host's packaging. It seems not all of texlive is available. -The RTEMS Documentation waf configure phase check for each texlive package used +The RTEMS Documentation waf configure phase checks for each texlive package used in the generated output and the styles. If you complete configure with the --pdf option you should be able to build PDF documentation. -The texlive package requirments come from the Latex styles we are using and +The texlive package requirements come from the Latex styles we are using and Sphinx. An example of failures are: @@ -384,7 +480,7 @@ warnings and extra information about the source to help make sure our documentation source is as clean as possible. Please use this when writing documentation or making updates. -The '--disable-extra-fonts' allows you to build PDF documents with out the +The '--disable-extra-fonts' allows you to build PDF documents without the fonts we use for a better quality document. Use this option to build without needing the extra fonts accepting you will get poor quality documents. @@ -423,7 +519,7 @@ existing documentation for an example and if unsure ask. 2. Do not insert tab characters, use spaces, no trailing white space. -3. Pasted text such as console output can exceed 80 columns however it is +3. Pasted text such as console output can exceed 80 columns; however, it is preferred even this text is wrapped at 80 columns. Long lines in code block text causes issues with the PDF output. @@ -437,7 +533,7 @@ existing documentation for an example and if unsure ask. 5 ^^^^^^ Sub-sub-sub-section 6 ~~~~~~ Sub-sub-sub-sub-section -5. For literal output, such as shell commands and code do not use '::' +5. For literal output such as shell commands and code, do not use '::' at the trailing edge of the previous paragraph as it generates warnings as the autodetect fails to find a suitable format. Use the '.. code-block::' with a suitable lexical label. The lexers are: @@ -462,9 +558,12 @@ existing documentation for an example and if unsure ask. The second is to use a single block of type 'none' with the command and output together as seen in a terminal session. The commands are - identifed by the standard shell prompt characters where '$' is a + identified by the standard shell prompt characters where '$' is a user prompt and '#' is a 'root' prompt. + Do not embed the version or version major number in the literal + commands or examples. Use the replacements listed in 10. + 6. Use the directives for 'note', 'warning', and 'topic'. Do not add 'TIP', 'Important' or 'Warning' to the text. Let the mark-up language handle this. The supported directives are: @@ -480,12 +579,12 @@ existing documentation for an example and if unsure ask. of images. To add an image use: .. figure:: ../images/my-image.png - :wdith: 75% + :width: 75% :align: center :alt: This is the alt text for some output types. -8. Callouts can be implemented manually using a literal block which can use - '::' or a code block and topic block is used for the items. For +8. Callouts can be implemented manually using a literal block ('::') + or a code block. Either way, a topic block is used for the items. For example: .. code-block: c @@ -508,10 +607,10 @@ existing documentation for an example and if unsure ask. 4. Exit with an exit code of 0. This value can be checked by the caller of this program. - Note, the topic items are manually numbered, which makes it easier to see + Note the topic items are manually numbered, which makes it easier to see which item matches the text. Use <> for the number and align at a position - that works and makes the number as visible as possible. Use hanging indents - if an items extends past a single line. + that makes the number as visible as possible. Use hanging indents + if an item extends past a single line. 9. Use the RTEMS domain references for URLs and mailing lists. For example to insert the RTEMS developers list use: @@ -543,3 +642,31 @@ existing documentation for an example and if unsure ask. bugs : https://devel.rtems.org/wiki/Bugs/ gsoc : https://devel.rtems.org/wiki/GSoC/ socis : https://devel.rtems.org/wiki/SOCIS/ + +10. Use the following to embed the version number in any part of the + documentation source: + + 1. @rtems-version@ + + The complete version string of the documentation. + + 2. @rtems-ver-major@ + + The version major number. + + 2. @rtems-ver-minor@ + + The version minor number. + + 2. @rtems-ver-revision@ + + The version revision number. + + The replacement happens during the source read phase of the build + and is not context specific. The substitution will happen in code + blocks and other normally quoted areas. + + It is a requirement these be used then embedded commands or + related text in the documentation to let the documentation track + the release. For example `microblaze-rtems6-gdb` should be written + as `microblaze-rtems@rtems-ver-major@-gdb`. |