doc: contribute: split style guidelines

Split style guidelines into multiple pages to allow expansion and adding
more details and levels.

Signed-off-by: Anas Nashif <[email protected]>

Author: nashif

doc/contribute/index.rst

@@ -18,7 +18,7 @@ General Guidelines
    contributor_expectations.rst
    reviewer_expectations.rst
    coding_guidelines/index.rst
-   style_guidelines.rst
+   style/index.rst
    proposals_and_rfcs.rst
    modifying_contributions.rst
 

doc/contribute/style/cmake.rst

@@ -3,10 +3,10 @@
 .. _cmake-style:
 
 CMake Style Guidelines
-======================
+######################
 
 General Formatting
-------------------
+******************
 
 - **Indentation**: Use **2 spaces** for indentation. Avoid tabs to ensure
   consistency across different environments.
@@ -30,7 +30,7 @@ General Formatting
      endif()
 
 Commands and Syntax
--------------------
+*******************
 
 - **Lowercase Commands**: Always use **lowercase** CMake commands (e.g.,
   ``add_executable``, ``find_package``). This improves readability and
@@ -59,7 +59,7 @@ Commands and Syntax
      target_sources(my_target PRIVATE src/file1.cpp src/file2.cpp)
 
 Variable Naming
----------------
+***************
 
 - **Use Uppercase for Cache Variables or variables shared across CMake files**:
   When defining cache variables using ``option`` or ``set(... CACHE ...)``, use
@@ -85,7 +85,7 @@ Variable Naming
      set(MYPROJECT_SRC_DIR "${CMAKE_SOURCE_DIR}/src")
 
 Quoting
--------
+*******
 
 - **Quote Strings and Variables**: Always quote string literals and variables
   to prevent unintended behavior, especially when dealing with paths or
@@ -107,7 +107,7 @@ Quoting
      option(BUILD_SHARED_LIBS "Build shared libraries" OFF)
 
 Avoid Hardcoding Paths
-----------------------
+**********************
 
 - Use CMake variables (``CMAKE_SOURCE_DIR``, ``CMAKE_BINARY_DIR``,
   ``CMAKE_CURRENT_SOURCE_DIR``) instead of hardcoding paths.
@@ -117,7 +117,7 @@ Avoid Hardcoding Paths
      set(output_dir "${CMAKE_BINARY_DIR}/bin")
 
 Conditional Logic
------------------
+*****************
 
 - Use ``if``, ``elseif``, and ``else`` with proper indentation, and close with
   ``endif()``.
@@ -129,7 +129,7 @@ Conditional Logic
      endif()
 
 Documentation
--------------
+*************
 
 - Use comments to document complex logic in the CMake files.
 

doc/contribute/style/code.rst

@@ -0,0 +1,38 @@
+.. _general_code_style:
+
+C Code and General Style Guidelines
+###################################
+
+Coding style is enforced on any new or modified code, but contributors are
+not expected to correct the style on existing code that they are not
+modifying.
+
+For style aspects where the guidelines don't offer explicit guidance or
+permit multiple valid ways to express something, contributors should follow
+the style of existing code in the tree, with higher importance given to
+"nearby" code (first look at the function, then the same file, then
+subsystem, etc).
+
+In general, follow the `Linux kernel coding style`_, with the following
+exceptions and clarifications:
+
+* Use `snake case`_ for code and variables.
+* The line length is 100 columns or fewer. In the documentation, longer lines
+  for URL references are an allowed exception.
+* Add braces to every ``if``, ``else``, ``do``, ``while``, ``for`` and
+  ``switch`` body, even for single-line code blocks.
+* Use spaces instead of tabs to align comments after declarations, as needed.
+* Use C89-style single line comments, ``/*  */``. The C99-style single line
+  comment, ``//``, is not allowed.
+* Use ``/**  */`` for doxygen comments that need to appear in the documentation.
+* Avoid using binary literals (constants starting with ``0b``).
+* Avoid using non-ASCII symbols in code, unless it significantly improves
+  clarity, avoid emojis in any case.
+* Use proper capitalization of nouns in code comments (e.g. ``UART`` and not
+  ``uart``, ``CMake`` and not ``cmake``).
+
+.. _Linux kernel coding style:
+   https://kernel.org/doc/html/latest/process/coding-style.html
+
+.. _snake case:
+   https://en.wikipedia.org/wiki/Snake_case

doc/contribute/style/devicetree.rst

@@ -0,0 +1,13 @@
+.. _devicetree_style:
+
+Devicetree Style Guidelines
+###########################
+
+  * Indent with tabs.
+  * Follow the Devicetree specification conventions and rules.
+  * Use dashes (``-``) as word separators for node and property names.
+  * Use underscores (``_``) as word separators in node labels.
+  * Leave a single space on each side of the equal sign (``=``) in property
+    definitions.
+  * Don't insert empty lines before a dedenting ``};``.
+  * Insert a single empty line to separate nodes at the same hierarchy level.

doc/contribute/style/index.rst

@@ -0,0 +1,87 @@
+.. _coding_style:
+
+
+Coding Style Guidelines
+#######################
+
+.. toctree::
+   :maxdepth: 1
+
+   code.rst
+   cmake.rst
+   devicetree.rst
+   kconfig.rst
+
+
+Style Tools
+***********
+
+Checkpatch
+==========
+
+The Linux kernel GPL-licensed tool ``checkpatch`` is used to check
+coding style conformity.
+
+.. note::
+   checkpatch does not currently run on Windows.
+
+Checkpatch is available in the scripts directory. To invoke it when committing
+code, make the file *$ZEPHYR_BASE/.git/hooks/pre-commit* executable and edit
+it to contain:
+
+.. code-block:: bash
+
+    #!/bin/sh
+    set -e exec
+    exec git diff --cached | ${ZEPHYR_BASE}/scripts/checkpatch.pl -
+
+Instead of running checkpatch at each commit, you may prefer to run it only
+before pushing on zephyr repo. To do this, make the file
+*$ZEPHYR_BASE/.git/hooks/pre-push* executable and edit it to contain:
+
+.. code-block:: bash
+
+    #!/bin/sh
+    remote="$1"
+    url="$2"
+
+    z40=0000000000000000000000000000000000000000
+
+    echo "Run push hook"
+
+    while read local_ref local_sha remote_ref remote_sha
+    do
+        args="$remote $url $local_ref $local_sha $remote_ref $remote_sha"
+        exec ${ZEPHYR_BASE}/scripts/series-push-hook.sh $args
+    done
+
+    exit 0
+
+If you want to override checkpatch verdict and push you branch despite reported
+issues, you can add option --no-verify to the git push command.
+
+A different way for running ``checkpatch`` is by using :ref:`check_compliance_py`
+script, which does additional style and compliance related checks.
+
+clang-format
+============
+
+The `clang-format tool <https://clang.llvm.org/docs/ClangFormat.html>`_ can
+be helpful to quickly reformat large amounts of new source code to our
+`Coding Style Guidelines`_ standards together with the ``.clang-format`` configuration file
+provided in the repository. ``clang-format`` is well integrated into most
+editors, but you can also run it manually like this:
+
+.. code-block:: bash
+
+   clang-format -i my_source_file.c
+
+``clang-format`` is part of LLVM, which can be downloaded from the project
+`releases page <https://github.com/llvm/llvm-project/releases>`_. Note that if
+you are a Linux user, ``clang-format`` will likely be available as a package in
+your distribution repositories.
+
+When there are differences between the `Coding Style Guidelines`_ guidelines and the
+formatting generated by code formatting tools, the `Coding Style Guidelines`_ guidelines
+take precedence. If there is ambiguity between formatting tools and the
+guidelines, maintainers may decide which style should be adopted.

doc/contribute/style/kconfig.rst

@@ -0,0 +1,14 @@
+.. _kconfig_style:
+
+Kconfig Style Guidelines
+########################
+
+  * Line length of 100 columns or fewer.
+  * Indent with tabs, except for ``help`` entry text which should be placed at
+    one tab plus two extra spaces.
+  * Leave a single empty line between option declarations.
+  * Use Statements like ``select`` carefully, see
+    :ref:`kconfig_tips_and_tricks` for more information.
+  * Format comments as ``# Comment`` rather than ``#Comment``
+  * Insert an empty line before/after each top-level ``if`` and ``endif``
+    statement.