doc: Fix layout of the shell documentation

Change-Id: I51613070cd1e8bc664212f33d985a6ecd217cee6
Signed-off-by: Anas Nashif <[email protected]>

Author: nashif

doc/subsystems/shell.rst

@@ -19,41 +19,44 @@ Use one of the following formats:
 
 Specific module's commands
 ==========================
-   `MODULE_NAME COMMAND`
-	One of the available modules is “KERNEL”, for the Kernel module.
-	More information can be found in :c:macro:`SHELL_REGISTER`.
+`MODULE_NAME COMMAND`
+ One of the available modules is “KERNEL”, for the Kernel module.  More
+ information can be found in :c:macro:`SHELL_REGISTER`.
 
 Help commands
 =============
-   `help`
-	Prints the available modules.
-   `help MODULE_NAME`
-   	Prints the names of the available commands for the module.
-   `help MODULE_NAME COMMAND`
-   	Prints help for the module's command (the help should show function
-	goal and required parameters).
+`help`
+ Prints the available modules.
+
+`help MODULE_NAME`
+ Prints the names of the available commands for the module.
+
+`help MODULE_NAME COMMAND`
+ Prints help for the module's command (the help should show function
+ goal and required parameters).
 
 Select module commands
 ======================
-   `set_module MODULE_NAME`
-	Use this command when using the shell only for one module.
-	After entering this command, you will not need to enter module
-	name in further	commands.
-	If the selected module has set a default shell prompt during its
-	initialization, the prompt will	be changed to that one.
-	Otherwise, the prompt will be changed to the selected module’s name to
-	reflect the current module in use.
-   `set_module`
-	Clears selected module. Restores prompt as well.
+`set_module MODULE_NAME`
+ Use this command when using the shell only for one module. After entering this
+ command, you will not need to enter module name in further commands. If
+ the selected module has set a default shell prompt during its initialization,
+ the prompt will be changed to that one. Otherwise, the prompt will be
+ changed to the selected module’s name to reflect the current module in use.
+
+`set_module`
+ Clears selected module. Restores prompt as well.
 
 Shell configuration
 *******************
 There are two levels of configuration: Infrastructure level and Module level.
 
 Infrastructure level
 ====================
+
 The default value for ENABLE_SHELL flag should be considered per product.
 This flag enables shell services.
+
 If it is enabled, kernel shell commands are also available for use.
 See the :option:`CONFIG_ENABLE_SHELL` Kconfig options for more information.
 
@@ -62,6 +65,7 @@ Module level
 Each module using shell service should add a unique flag in its Kconfig file.
 
 Example:
+
 CONFIG_SAMPLE_MODULE_USE_SHELL=y
 
 In the module’s code, the shell usage depends on this config parameter.
@@ -73,51 +77,51 @@ The default value for ENABLE_SHELL flag should be considered per product.
 
 Configuration steps to add shell functionality to a module
 ==========================================================
+
  #. Check that ENABLE_SHELL is set to yes.
  #. Add the module unique flag to its Kconfig file.
 
-
 Writing a shell module
 **********************
+
 In order to support shell in your module, the application must do the following:
 
- #. Module configuration flag:
-	Declare a new flag in your module Kconfig file.
-	It should depend on `ENABLE_SHELL` flag.
+#. Module configuration flag: Declare a new flag in your module Kconfig file.
+   It should depend on `ENABLE_SHELL` flag.
+
+#. Module registration to shell: Add your shell identifier and register its
+   callback functions in the shell database using :c:macro:`SHELL_REGISTER`.
+
+Optionally, you can use one of the following API functions to override default
+behvior and settings:
 
- #. Module registration to shell:
-	Add your shell identifier and register its callback functions in the
-	shell database using :c:macro:`SHELL_REGISTER`.
+* :c:func:`shell_register_default_module`
 
- #. Optional:
-	:c:func:`shell_register_default_module`
+* :c:func:`shell_register_prompt_handler`
 
-	:c:func:`shell_register_prompt_handler`
+In case of a sample applications as well as test environment, user can choose to
+set a default module in code level. In this case, the function
+shell_register_default_module should be called after calling SHELL_REGISTER in
+application level.  If the function shell_register_prompt_handler was called as
+well, the prompt will be changed to that one.  Otherwise, the prompt will be
+changed to the selected module’s name, in order to reflect the current module in
+use.
 
-	Usage:
-		In case of a sample applications as well as test environment,
-		user can choose to set a default module in code level.
-		In this case, the function shell_register_default_module should
-		be called after calling SHELL_REGISTER in application level.
-		If the function shell_register_prompt_handler was called
-		as well, the prompt will be changed to that one.
-		Otherwise, the prompt will be changed to the selected module’s
-		name, in order to reflect the current module in use.
 
-	Note:
-		Even if a default module was set in code level, it can be
-		overwritten by “set_module” shell command.
+.. note::
+        Even if a default module was set in code level, it can be overwritten by
+        “set_module” shell command.
 
-	When to use shell_register_default_module:
+You can use  :c:func:`shell_register_default_module` in the following cases:
 
-	* Use this command in case of using the shell only for one module.
-	  After entering this command, no need to enter module name in further
-	  commands.
+* Use this command in case of using the shell only for one module.
+  After entering this command, no need to enter module name in further
+  commands.
 
-	* Use this function for shell backward compatibility.
+* Use this function for shell backward compatibility.
 
-	More details on those optional functions can be found
-	in :ref:`shell_api_functions`.
+More details on those optional functions can be found in
+:ref:`shell_api_functions`.
 
 
 .. _shell_api_functions:

include/misc/shell.h

@@ -46,8 +46,8 @@ struct shell_module {
 
 
 /**
- * @brief Kernel Shell Api
- * @defgroup _shell_api_functions Shell Api Functions
+ * @brief Kernel Shell API
+ * @defgroup _shell_api_functions Shell API Functions
  * @{
  */