Contributing to the Clear Linux* OS is all about code. Therefore, your documentation must include as many code examples as possible. You can write code examples directly in the documentation or include them from a source file. Use these guidelines to insert code blocks to your documentation:

  • Include code examples from a source file. Only write the code example directly into the documentation if the example is less than 10 lines long.
  • Use the :linenos: option of the literalinclude directive to add line numbers to your example.
  • Specify the programing language of your example. Not only will it add syntax highlighting but it also allows the reader to identify code efficiently. Use bash for console commands, asm for assembly code and c for C code.
  • Treat all console commands entered by users as code examples.

Examples

This is a code example included from a file. Note how only certain lines of the source file are included and how the lines are renumbered.

This source:

.. literalinclude:: ./hello.c
   :language: c
   :lines: 97-110
   :linenos:

Renders as:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
/**
 * @brief Exchanges Hello messages with taskA.
 *
 * Actions:
 *  -# Calls function helloLoop, thus taskB exchanges hello messages with taskA.
 */
void taskB(void)
{
	helloLoop (__FUNCTION__, TASKBSEM, TASKASEM); /* Action 1 */
}

#else

This example shows a series of console commands. Line numbering is not required. Specify that these are commands using bash as the programing language.

This source:

.. code-block:: bash

   $ mkdir ${HOME}/x86-build

   $ mkdir ${HOME}/arm-build

   $ mkdir ${HOME}/cross-src

Renders as:

$ mkdir ${HOME}/x86-build

$ mkdir ${HOME}/arm-build

$ mkdir ${HOME}/cross-src

Note

You will find instances which use console instead of bash. We are currently in the process of implementing a distinction between the two. Moving forward, bash will be used for commands entered by readers, and console will be used for the output users obtain in the command prompt.

Finally, this is a code example that is not part of the Clear Linux OS code base. It is not even valid code but it can illustrate the concept.

This source:

.. code-block:: c

   static NANO_CPU_INT_STUB_DECL (deviceStub);

   void deviceDriver (void)

   {

   .
   .
   .

   nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler,
   deviceStub);

   .
   .
   .

   }

Renders as:

static NANO_CPU_INT_STUB_DECL (deviceStub);

void deviceDriver (void)

{

.
.
.

nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler,
deviceStub);

.
.
.

}

Templates

We included templates for a basic .. code-block:: directive and for a .. literalinclude:: directive.

Use code-block for console commands, brief examples, and examples outside the Clear Linux OS code base.

.. code-block:: language

   source

Use litteralinclude to insert code from a source file. Keep in mind that you can include the entire contents of the file or just specific lines.

.. literalinclude:: ../path/to/file/file_name.c
   :language: c
   :lines: 5-30, 32, 70-100
   :emphasize-lines: 3
   :linenos:

Caution

The :emphasize-lines: option uses the line numbering provided by :linenos:. The emphasized line in the template will be the third one of the example but the eighth one of the source file.