[rtems-docs commit] eng: Add documentation guidelines

[Sebastian Huber]

Module:    rtems-docs
Branch:    master
Commit:    2c7cd341a038776843f4f29ccde7b3dc3d2b15a7
Changeset: http://git.rtems.org/rtems-docs/commit/?id=2c7cd341a038776843f4f29ccde7b3dc3d2b15a7

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Thu Apr  2 10:22:42 2020 +0200

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.

---

 c-user/config/intro.rst | 44 ---------------------------
 eng/doc-guide.rst       | 79 +++++++++++++++++++++++++++++++++++++++++++++++++
 eng/management.rst      |  1 +
 3 files changed, 80 insertions(+), 44 deletions(-)

diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst
index 46267d7..4c2f715 100644
--- a/c-user/config/intro.rst
+++ b/c-user/config/intro.rst
@@ -151,50 +151,6 @@ In general, ``<rtems/confdefs.h>`` is very accurate when given enough
 information.  However, it is quite easy to use a library and forget to account
 for its resources.
 
-Format to be followed for making changes in this file
-=====================================================
-
-MACRO NAME:
-  Should be alphanumeric. Can have '_' (underscore).
-
-DATA TYPE:
-  Please refer to all existing formats.
-
-RANGE:
-  The range depends on the Data Type of the macro.
-
-  - If the data type is of type task priority, then its value should be an
-    integer in the range of 1 to 255.
-
-  - If the data type is an integer, then it can have numbers, characters (in
-    case the value is defined using another macro) and arithmetic operations
-    (+, -, \*, /).
-
-  - If the data type is a function pointer the first character should be an
-    alphabet or an underscore. The rest of the string can be alphanumeric.
-
-  - If the data type is RTEMS Attributes or RTEMS Mode then the string should
-    be alphanumeric.
-
-  - If the data type is RTEMS NAME then the value should be an integer>=0 or
-    ``RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' )``
-
-DEFAULT VALUE:
-  The default value should be in the following formats- Please note that the
-  '.' (full stop) is necessary.
-
-  - In case the value is not defined then: This is not defined by default.
-
-  - If we know the default value then: The default value is XXX.
-
-  - If the default value is BSP Specific then: This option is BSP specific.
-
-DESCRIPTION:
-  The description of the macro. (No specific format)
-
-NOTES:
-  Any further notes. (No specific format)
-
 Configuration Example
 =====================
 
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.
diff --git a/eng/management.rst b/eng/management.rst
index 6eb4217..6a8e057 100644
--- a/eng/management.rst
+++ b/eng/management.rst
@@ -16,6 +16,7 @@ Software Development Management
     vc-users
     vc-authors
     coding
+    doc-guide
     python-devel
     change-management
     issue-tracking