rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-04 18:07:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

README: Minor clarifications and fixes

Browse Source 
Fixed some minor typographical errors.
Updated a dead link.
Reworded some sentences for clarity.
This commit is contained in:
Stephen Clark 2021-07-15 11:08:41 -05:00 committed by Joel Sherrill
parent 821b624ece
commit 84f7c6a7ef
1 changed files with 25 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
README.txt
View File

@ -1,16 +1,17 @@
RTEMS Project Documentation RTEMS Project Documentation
=========================== ===========================
The documents are written in ReST and built using Sphinx. The build system will The documents are written in ReST and built using Sphinx. The waf build system
check the version of Sphinx and ensure you have a suitable version 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 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. 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 ReST is the Re-Structured-Text format. It is a simple markup language that
us to create quality documentaion. It is flexible and powerful however does not allows us to create quality documentation which can easily be converted to
attempt to train it to create a specific format. You need to test any new way multiple different formats. This flexibility is convenient, but you still need
of presenting something on all output formats. What may look great in one to test any new way of presenting something on all output formats. What may look
format may not translate with the same clarity to another output format. great in one format may not translate with the same clarity to another output
format.
The RTEMS Documentation output formats are: The RTEMS Documentation output formats are:
@ -26,7 +27,7 @@ Images can be created from source using PlantUML and Ditaa.
A Sphinx checksheet is: 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 Production Quality Hosts
------------------------ ------------------------
@ -45,7 +46,7 @@ NOTE: RedHat Enterprise Linux (RHEL) and Fedora should be the same as CentOS.
Images Images
------ ------
All images should be placed int he 'images' directory and referenced from the All images should be placed in the 'images' directory and referenced from the
ReST with a relative path. This lets us shared and control images. ReST with a relative path. This lets us shared and control images.
We prefer being able to build images from source. This is not always possible We prefer being able to build images from source. This is not always possible
@ -85,7 +86,7 @@ The home page contain the language options. The PlantUML online demo server
supports Ditaa so use that resource as an online tool. The Ditaa image source supports Ditaa so use that resource as an online tool. The Ditaa image source
extension is '.ditaa'. 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 online resources can be used. Save the source and the generated PNG file in the
same directory under 'images'. same directory under 'images'.
@ -94,12 +95,12 @@ Host Setup
HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install, HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install,
and building a Single HTML page requires the 'inliner' tool. The 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 package called 'node-plantuml' which installs the 'puml' command and Ditaa needs
the 'ditaa' command and package. Ditaa images are built using the 'puml' the 'ditaa' command and package. Ditaa images are built using the 'puml'
command. 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 The best results are produced with Python3 and a virtual environment`. It can
create a specific python environment using `pip`. create a specific python environment using `pip`.
@ -107,8 +108,8 @@ create a specific python environment using `pip`.
Virtual Environment Virtual Environment
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
Create a directory to house the virtual environment, create the envrionment Create a directory to house the virtual environment, create the environment,
and the activate it. This example assumes Python3 and the `venv` module: and then activate it. This example assumes Python3 and the `venv` module:
$ mkdir sphinx $ mkdir sphinx
$ python3 -m venv sphinx $ python3 -m venv sphinx
@ -120,7 +121,7 @@ Alternatively you can use the `virtualenv` command:
$ virtualenv sphinx $ virtualenv sphinx
$ . ./sphinx/bin/activate $ . ./sphinx/bin/activate
The prompt will now change. You can install Sphinx with: Either way, the prompt will now change. You can install Sphinx with:
$ pip install sphinx $ pip install sphinx
$ pip install sphinxcontrib-bibtex $ pip install sphinxcontrib-bibtex
@ -321,11 +322,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 package is present in a host's packaging. It seems not all of texlive is
available. 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 in the generated output and the styles. If you complete configure with the
--pdf option you should be able to build PDF documentation. --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. Sphinx.
An example of failures are: An example of failures are:
@ -450,7 +451,7 @@ existing documentation for an example and if unsure ask.
2. Do not insert tab characters, use spaces, no trailing white space. 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 preferred even this text is wrapped at 80 columns. Long lines in code block
text causes issues with the PDF output. text causes issues with the PDF output.
@ -464,7 +465,7 @@ existing documentation for an example and if unsure ask.
5 ^^^^^^ Sub-sub-sub-section 5 ^^^^^^ Sub-sub-sub-section
6 ~~~~~~ Sub-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 at the trailing edge of the previous paragraph as it generates
warnings as the autodetect fails to find a suitable format. Use the warnings as the autodetect fails to find a suitable format. Use the
'.. code-block::' with a suitable lexical label. The lexers are: '.. code-block::' with a suitable lexical label. The lexers are:
@ -511,8 +512,8 @@ existing documentation for an example and if unsure ask.
:align: center :align: center
:alt: This is the alt text for some output types. :alt: This is the alt text for some output types.
8. Callouts can be implemented manually using a literal block which can use 8. Callouts can be implemented manually using a literal block ('::')
'::' or a code block and topic block is used for the items. For or a code block. Either way, a topic block is used for the items. For
example: example:
.. code-block: c .. code-block: c
@ -535,9 +536,9 @@ existing documentation for an example and if unsure ask.
4. Exit with an exit code of 0. This value can be checked by the 4. Exit with an exit code of 0. This value can be checked by the
caller of this program. 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 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 that makes the number as visible as possible. Use hanging indents
if an items extends past a single line. if an items extends past a single line.
9. Use the RTEMS domain references for URLs and mailing lists. For example to 9. Use the RTEMS domain references for URLs and mailing lists. For example to