doc: Document some Kconfig best practices and tips

Add a new 'Kconfig tips and best practices' page that covers some
Kconfig best practices, tips, and arcana, like the following:

 - What should be turned into a Kconfig symbol?

 - Best practices and pitfalls for 'select'

 - Factoring out common dependencies

 - Kconfig shorthands

 - Redundant defaults

 - Explanations of various more obscure Kconfig features, like 'imply',
   optional prompts, optional choices, and 'visible if'

Link the new page in the sidebar (under Developer Guides), the
application development primer, and the architecture and board porting
guides.

Perhaps other, more Zephyr-specific information could be added later on
as well, but this is a good start.

Include some other Kconfig-related documentation improvements as well:

 - In the application development primer, give 'CONFIG_FOO=n' as the way
   to set a bool symbol to 'n', instead of '# CONFIG_FOO is not set'.
   That seems to be what people usually do in practice in Zephyr.

   Explain why '# CONFIG_FOO is not set' works as well. There's a
   technical reason for it, related to Make.

 - Mention that the recommended syntax for referencing environment
   variables is now $(FOO) (which uses the Kconfig preprocessor)

 - Mention that the kconfiglib.py docstring has more in-depth
   information about how symbol values are calculated.

Signed-off-by: Ulf Magnusson <[email protected]>

Author: ulfalizer

doc/application/application.rst

@@ -997,6 +997,8 @@ development, as described below in :ref:`override_kernel_conf`.
 
 For more information on Zephyr's Kconfig configuration scheme, see the
 :ref:`setting_configuration_values` section in the :ref:`board_porting_guide`.
+For some tips and general recommendations when writing Kconfig files, see the
+:ref:`kconfig_tips_and_tricks` page.
 
 For information on available kernel configuration options, including
 inter-dependencies between options, see the :ref:`configuration`.
@@ -1022,18 +1024,26 @@ This section describes how to edit Zephyr configuration
 
 - Add each configuration entry on a new line.
 
-- Enable a boolean option by setting its value to ``y``:
+- Enable or disable a boolean option by setting its value to ``y`` or ``n``:
 
   .. code-block:: none
 
      CONFIG_SOME_BOOL=y
+     CONFIG_SOME_OTHER_BOOL=n
 
-  To ensure that a boolean configuration option is not set, add a line
-  like this instead (including the leading ``#`` symbol):
+  .. note::
 
-  .. code-block:: none
+     Another way to set a boolean symbol to ``n`` is with a comment with the
+     following format:
+
+     .. code-block:: none
+
+        # CONFIG_SOME_OTHER_BOOL is not set
 
-     # CONFIG_SOME_BOOL is not set
+     This style is accepted for a technical reason: Kconfig configuration files
+     can be parsed as makefiles (though Zephyr doesn't use this). Having
+     ``n``-valued symbols correspond to unset variables simplifies tests in
+     Make.
 
 - You can set integer and string options as well, like this:
 

doc/application/index.rst

@@ -11,6 +11,7 @@ Developer Guides
    ../reference/kconfig/index.rst
    ../api/api.rst
    ../porting/porting.rst
+   kconfig-tips.rst
    ../README.rst
    ../west/index.rst
    coccinelle.rst