mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-07-02 10:46:00 +00:00
Kristal Dale
162 lines
3.4 KiB
ReStructuredText
162 lines
3.4 KiB
ReStructuredText
.. _code:
|
|
|
|
Code blocks
|
|
###########
|
|
|
|
Contributing to the |CL-ATTR| 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:
|
|
|
|
.. code-block:: rst
|
|
|
|
.. literalinclude:: ./hello.c
|
|
:language: c
|
|
:lines: 97-110
|
|
:linenos:
|
|
|
|
Renders as:
|
|
|
|
.. 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.
|
|
|
|
This source:
|
|
|
|
.. code-block:: rst
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mkdir ${HOME}/x86-build
|
|
|
|
$ mkdir ${HOME}/arm-build
|
|
|
|
$ mkdir ${HOME}/cross-src
|
|
|
|
Renders as:
|
|
|
|
.. 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.
|
|
|
|
This source:
|
|
|
|
.. code-block:: rest
|
|
|
|
.. code-block:: c
|
|
|
|
static NANO_CPU_INT_STUB_DECL (deviceStub);
|
|
|
|
void deviceDriver (void)
|
|
|
|
{
|
|
|
|
.
|
|
.
|
|
.
|
|
|
|
nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler,
|
|
deviceStub);
|
|
|
|
.
|
|
.
|
|
.
|
|
|
|
}
|
|
|
|
Renders as:
|
|
|
|
.. 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 ``:linenos:``. The emphasized line in the template will be the
|
|
third one of the example but the eighth one of the source file.
|
|
|