doc: contribute: split style guidelines into own document
Move style guidelines into own section and put it along side other
guidelines.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
diff --git a/doc/contribute/guidelines.rst b/doc/contribute/guidelines.rst
index a2c4fe4..2dd9566 100644
--- a/doc/contribute/guidelines.rst
+++ b/doc/contribute/guidelines.rst
@@ -506,146 +506,6 @@
Link: https://github.com/zephyrproject-rtos/zephyr/issues/<issue number>
-.. _coding_style:
-
-Coding Style
-============
-
-.. note::
- 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.
-
-.. note::
- 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).
-
-.. _Linux kernel coding style:
- https://kernel.org/doc/html/latest/process/coding-style.html
-
-.. _snake case:
- https://en.wikipedia.org/wiki/Snake_case
-
-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``).
-
-Beyond C code, the following coding style rules apply to other types of files:
-
-* CMake
-
- * Indent with spaces, indentation is two spaces.
- * Don't use space between commands (e.g. ``if``) and the corresponding opening
- bracket (e.g. ``(``).
-
-* Devicetree
-
- * 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.
-
-* Kconfig
-
- * 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``
-
-Use these coding guidelines to ensure that your development complies with the
-project's style and naming conventions.
-
-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 more complete alternative to this is using :ref:`check_compliance_py` script.
-
-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`_ 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 and the
-formatting generated by code formatting tools, the `Coding Style`_ guidelines
-take precedence. If there is ambiguity between formatting tools and the
-guidelines, maintainers may decide which style should be adopted.
-
.. _Continuous Integration:
Continuous Integration (CI)
diff --git a/doc/contribute/index.rst b/doc/contribute/index.rst
index 77ecfa6..8b364aa 100644
--- a/doc/contribute/index.rst
+++ b/doc/contribute/index.rst
@@ -18,6 +18,7 @@
contributor_expectations.rst
reviewer_expectations.rst
coding_guidelines/index.rst
+ style_guidelines.rst
proposals_and_rfcs.rst
modifying_contributions.rst
@@ -41,8 +42,9 @@
Code contributions are expected to follow a set of coding guidelines to ensure consistency and
readability across the code base.
- This page describes these guidelines and introduces important considerations regarding the use of
- :ref:`inclusive language <coding_guideline_inclusive_language>`.
+:ref:`coding_style`
+ Code contributions are expected to follow a set of style guidelines to ensure consistency and
+ readability across the code base.
:ref:`rfcs`
Learn when and how to submit RFCs (Request for Comments) for new features and changes to the
diff --git a/doc/contribute/style_guidelines.rst b/doc/contribute/style_guidelines.rst
new file mode 100644
index 0000000..0a282af
--- /dev/null
+++ b/doc/contribute/style_guidelines.rst
@@ -0,0 +1,150 @@
+.. _coding_style:
+
+
+Coding Style Guidelines
+#######################
+
+C Code and General Style
+************************
+
+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``).
+
+Beyond C code, the following coding style rules apply to other types of files:
+
+CMake
+*****
+
+ * Indent with spaces, indentation is two spaces.
+ * Don't use space between commands (e.g. ``if``) and the corresponding opening
+ bracket (e.g. ``(``).
+
+Devicetree
+**********
+
+ * 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.
+
+Kconfig
+*******
+
+ * 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.
+
+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.
+
+
+.. _Linux kernel coding style:
+ https://kernel.org/doc/html/latest/process/coding-style.html
+
+.. _snake case:
+ https://en.wikipedia.org/wiki/Snake_case
