Documentation Style

Here are some guidelines and best practices for contributing to Cilium’s documentation. They have several objectives:

  • Ensure that the documentation is rendered in the best possible way (in particular for code blocks).
  • Make the documentation easy to maintain and extend.
  • Help keep a consistent style throughout the documentation.

See also the documentation for testing for instructions on how to preview documentation changes.

Titles

Prefer title case (capital letters on most words of the title) rather than sentence case for titles. See this link if necessary: https://titlecaseconverter.com/.

Body

Wrap the lines for long sentences or paragraphs. There is no fixed convention on the length of lines, but targeting a width of about 80 characters should be safe in most circumstances.

Code Blocks

Code snippets and other literal blocks usually fall under one of those three categories:

  • They contain substitution references (for example: |SCM_WEB|). In that case, always use the .. parsed-literal directive, otherwise the token will not be substituted.

    Prefer:

    .. parsed-literal::
    
        $ kubectl create -f \ |SCM_WEB|\/examples/minikube/http-sw-app.yaml
    

    Avoid:

    .. code-block:: shell-session
    
        $ kubectl create -f \ |SCM_WEB|\/examples/minikube/http-sw-app.yaml
    
  • If the text is not a code snippet, but just some fragment that should be printed verbatim (for example, the unstructured output of a shell command), use the marker for literal blocks (::).

    Prefer:

    See the output in ``dmesg``:
    
    ::
    
        [ 3389.935842] flen=6 proglen=70 pass=3 image=ffffffffa0069c8f from=tcpdump pid=20583
        [ 3389.935847] JIT code: 00000000: 55 48 89 e5 48 83 ec 60 48 89 5d f8 44 8b 4f 68
    
    See more output in ``dmesg``::
    
        [ 3389.935849] JIT code: 00000010: 44 2b 4f 6c 4c 8b 87 d8 00 00 00 be 0c 00 00 00
        [ 3389.935850] JIT code: 00000020: e8 1d 94 ff e0 3d 00 08 00 00 75 16 be 17 00 00
    

    Avoid:

    See the output in ``dmesg``:
    
    .. parsed-literal::
    
        [ 3389.935842] flen=6 proglen=70 pass=3 image=ffffffffa0069c8f from=tcpdump pid=20583
        [ 3389.935847] JIT code: 00000000: 55 48 89 e5 48 83 ec 60 48 89 5d f8 44 8b 4f 68
    

    The reason is that because these snippets contain no code, there is no need to mark them as code or parsed literals. The former would tell Sphinx to attempt to apply syntax highlight, the second would tell it to look for reStructuredText markup to parse in the block.

  • If the text contained code or structured output, use the .. code-block directive. Do not use the .. code directive, which is slightly less flexible.

    Prefer:

    .. code-block:: shell-session
    
        $ ls
        cilium
        $ cd cilium/
    

    Avoid:

    .. parsed-literal::
    
        $ ls
        cilium
        $ cd cilium/
    
    .. code-block:: bash
    
        $ ls
        cilium
        $ cd cilium/
    
    .. code-block:: shell-session
    
        ls
        cilium
        cd cilium/
    

    The .. code-block directive should always take a language name as argument, for example: .. code-block:: yaml or .. code-block:: shell-session. The use of bash is possible but should be limited to Bash scripts. For any listing of shell commands, and in particular if the snippet mixes commands and their output, use shell-session, which will bring the best coloration and may trigger the generation of the Copy commands button.

For snippets containing shell commands, in particular if they also contain the output for those commands, use prompt symbols to prefix the commands. Use $ for commands to run as a normal user, and # for commands to run with administrator privileges. You may use sudo as an alternative way to mark commands to run with privileges.

Lists

  • Left-align the body of a list item with the text on the first line, after the item symbol.

    Prefer:

    - The text in this item
      wraps of several lines,
      with consistent indentation.
    

    Avoid:

    - The text in this item
        wraps on several lines
        and the indent is not consistent
        with the first line.
    
  • For enumerated lists, prefer auto-numbering with the #. marker rather than manually numbering the sections.

    Prefer:

    #. First item
    #. Second item
    

    Avoid:

    1. First item
    2. Second item
    

Roles

  • We have a dedicated role for referencing Cilium GitHub issues, to reference them in a consistent fashion. Use it when relevant.

    Prefer:

    See :gh-issue:`1234`.
    

    Avoid:

    See `this GitHub issue <https://github.com/cilium/cilium/issues/1234>`__.