eng: Add documentation guidelines

Start with templates for the application configuration options.

Remove "Format to be followed for making changes in this file" from
c-user.

Update #3910.

1 files changed, 79 insertions, 0 deletions

diff --git a/eng/doc-guide.rst b/eng/doc-guide.rst
new file mode 100644
index 0000000..cdcd04f
--- /dev/null
+++ b/eng/doc-guide.rst
@@ -0,0 +1,79 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. _DocGuide:
+
+Documentation Guidelines
+************************
+
+Application Configuration Options
+=================================
+
+Add at least an index entry and a label for the configuration option.  Use a
+pattern of ``CONFIGURE_[A-Z0-9_]+`` for the option name.  Use the following
+template for application configuration feature options:
+
+.. code-block:: rst
+
+    .. index:: CONFIGURE_FEATURE
+
+    .. _CONFIGURE_FEATURE:
+
+    CONFIGURE_FEATURE
+    -----------------
+
+    CONSTANT:
+        ``CONFIGURE_FEATURE``
+
+    OPTION TYPE:
+        This configuration option is a boolean feature define.
+
+    DEFAULT CONFIGURATION:
+        If this configuration option is undefined, then the described feature is not
+        enabled.
+
+    DESCRIPTION:
+        In case this configuration option is defined, then feature happens.
+
+    NOTES:
+        Keep the description short.  Add all special cases, usage notes, error
+        conditions, configuration dependencies, references, etc. here to the notes.
+
+Use the following template for application configuration integer and
+initializer options:
+
+.. code-block:: rst
+
+    .. index:: CONFIGURE_VALUE
+
+    .. _CONFIGURE_VALUE:
+
+    CONFIGURE_VALUE
+    -----------------
+
+    CONSTANT:
+        ``CONFIGURE_VALUE``
+
+    OPTION TYPE:
+        This configuration option is an integer (or initializer) define.
+
+    DEFAULT VALUE:
+        The default value is X.
+
+    VALUE CONSTRAINTS:
+        The value of this configuration option shall satisfy all of the following
+        constraints:
+
+        * It shall be greater than or equal to A.
+
+        * It shall be less than or equal to B.
+
+        * It shall meet C.
+
+    DESCRIPTION:
+        The value of this configuration option defines the Y of Z in W.
+
+    NOTES:
+        Keep the description short.  Add all special cases, usage notes, error
+        conditions, configuration dependencies, references, etc. here to the notes.