[PATCH] eng: Add documentation guidelines

[Chris Johns]

On 2020-04-02 19:25, Sebastian Huber wrote:
> Start with templates for the application configuration options.
> 
> Remove "Format to be followed for making changes in this file" from
> c-user.
> 
> Update #3910.

OK.

Chris

> ---
>   c-user/config/intro.rst | 44 ---------------------------
>   eng/doc-guide.rst       | 79 +++++++++++++++++++++++++++++++++++++++++++++++++
>   eng/management.rst      |  1 +
>   3 files changed, 80 insertions(+), 44 deletions(-)
>   create mode 100644 eng/doc-guide.rst
> 
> 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
>