New Chapter

This page describes how to write a new chapter in the documentation and the rules you should follow.

NOTE:

1. ReST and Sphinx manage the layout so do not attempt to create a specific layout with ReST. It may and will change in ways you do not expect.

2. Check all output formats until you are comfortable with the look and what is happening.

ReST Coding Standard

We have a coding standard for how we use ReST. It is important we use this standard. The standard is documented in ​README.txt.

Headings

Use the following for headings:

1. ###### Part
2. ****** Section
3. ====== Sub-section
4. ------ Sub-sub-section
5. ^^^^^^ Sub-sub-sub-section
6. ~~~~~~ Sub-sub-sub-sub-section

The specific character needs to be the same length as the heading.

Source Files

Add a new chapter in a new ReST source file. Use the .rst file extension. The waf build system will build all .rst files it finds.

License

All RTEMS Documentation is under the CC-BY-SA-4.0 license and we require the first line be:

.. comment SPDX-License-Identifier: CC-BY-SA-4.0

After this you can add a copyright statement. For example:

.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org>
.. comment: All rights reserved.

Chapter Title

Add the Chapter title:

RTEMS Is Awesome
****************

You can optionally follow the Chapter title with some text about the chapter or you can start into a section. No chapter text leaves you with a blank page in the PDF format which can look nice acting as a separator. See the c-user manual for an example of this.

Sections and Sub-Sections

Add sections and sub-sections to your chapter breaking the text into sensible grouping. For example:

.. _why_use_rtems:

Why I use RTEMS?
================
.. index: Why use RTEMS?

I use RTEMS because is it reliable, stable and *free*.

ReST will automatically provide an anchor you can reference based on the section heading. To reference the section simply add:

There are many reasons to use RTEMS, see :ref:`Why I use RTEMS?`.

In this example another anchor has been provided called why_use_rtems and it can also be referenced using:

There are many reasons to use RTEMS, see :ref:`why_use_rtems`.

If you want to avoid breaking references with changes in section naming then an explicit anchor is best.

An index entry has also been added.

Literal Test

To use literal text, that is text that appears in a constant width font use:

``MY_CONSTANT``

Code Blocks

To add code blocks use:

.. code-block:: c

   void foo(cons char* bar)
   {
      printf("Hello from: %s\n", bar);
   }

NOTE: You need a line between the ..code-block:: and the start of the code.

You can select from a number of formats, for example c and shell.

Directives

Directives use the ReST definition format:

DESCRIPTION:
    Indent the text for the description and everything in the description is
    part of the description until you add a paragraph in column 1. This 
    includes code blocks:

    .. code-block: shell

       # cd /
       # rm -rf *

    And you can lists:

       #. Point 1
       #. Point 2

NOTES:
    A new part of the directive.

Figures and Images

Figures and images are the same thing. Please the image in the images directory tree so we can share images where ever possible. Also place the source for the image it the image is built in some way. Where possible avoid using proprietary tools to create images because this creates a burden for the project to maintain the image. Also provide details on how to edit or recreate the image.

In the ReST source use:

.. figure:: ../images/eclipse/eclipse-help-installation.png
   :width: 50%
   :align: center
   :alt: Help, Installation Details

The modifiers help position and layout the image in the output.

PDF Page Breaks

RTEMS Documentation requires we start a new directory, command or item on a new page. In HTML we have no control over this and it does not make sense. In the PDF it requires we add specific Latex commands:

.. raw:: latex

   \clearpage

For example from the c-user manual for the Semaphore Manager:

Directives
==========

This section details the semaphore manager's directives.  A subsection is
dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.

.. raw:: latex

   \clearpage

.. _rtems_semaphore_create:

SEMAPHORE_CREATE - Create a semaphore
-------------------------------------
.. index:: create a semaphore
.. index:: rtems_semaphore_create


CALLING SEQUENCE:
    .. code-block:: c

        rtems_status_code rtems_semaphore_create(
            rtems_name           name,
            uint32_t             count,
            rtems_attribute      attribute_set,
            rtems_task_priority  priority_ceiling,
            rtems_id            *id
        );