clear-linux-documentation/source/clear-linux/reference/collaboration/documentation/code.rst

.. _code:

Code blocks
###########

Collaborating to the |CLOSIA| is all about code. Therefore, your
documentation must include code examples. The code examples can be written
directly in the documentation or included 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 ``:lineos:`` option of the directives to add line numbers to
  your example if it is larger than 12 lines.

* 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.

Renders as:

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

From the source:

.. code-block:: rst

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


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

Renders as:

.. code-block:: bash

   $ mkdir ${HOME}/x86-build

   $ mkdir ${HOME}/arm-build

   $ mkdir ${HOME}/cross-src

From the source:

.. code-block:: rst

   .. code-block:: bash

      $ 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 |CL| code base. It is
not even valid code but it can illustrate the concept.

Renders as:

.. code-block:: c

   static NANO_CPU_INT_STUB_DECL (deviceStub);

   void deviceDriver (void)

   {

   .
   .
   .

   nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler,
   deviceStub);

   .
   .
   .

   }

From the source:

.. code-block:: rest

   .. code-block:: c

      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 |CL| code base.

.. code-block:: rst

   .. 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.

.. code-block:: rst

   .. 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 ``:lineos:``. The emphasized line in the template will be the
   third one of the example but the eighth one of the source file.