doc: API documentation refactoring.

Restructured the API documentation and moved it from the Reference
section to the Developer guides section.

Added a note about the search function to help users find the API they
are looking for faster.

Splitted the API docs into two files one for nanokernel and another for
the microkernel APIs.

Added table of contents for each of the API sections with a back link on
the headings to take the users back to the top of the page. Making
navigation easier and more user friendly.

Change-Id: I80f415a60ea9c7df22276b464013e906e1efa511
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>

doc/api/api.rst

@@ -0,0 +1,21 @@
+.. _api:
+
+API Documentation
+#################
+
+Welcome to the Zephyr Project's
+:abbr:`API (Application Programing Interface)` documentation.
+
+This section contains the API documentation automatically extracted from the
+code. To ease navigation, we have split the APis in nanokernel APIs and
+microkernel APIs. If you are looking for a specific API, enter it on the
+search box. The search results display all sections containing information
+about that API.
+
+The use of the Zephyr APIs is the same for all platforms and boards.
+
+.. toctree::
+   :maxdepth: 2
+
+   nanokernel_api.rst
+   microkernel_api.rst

doc/api/microkernel_api.rst

@@ -1,128 +1,78 @@
-.. _api:
+.. microkernel_api:
 
-API Documentation
+Microkernel APIs
-#################
+################
 
-Nanokernel
+.. contents::
-**********
+   :depth: 1
-
+   :local:
-Fibers
+   :backlinks: top
-======
-
-.. doxygengroup:: nanokernel_fiber
-   :project: Zephyr
-   :content-only:
-
-Semaphores
-==========
-
-.. doxygengroup:: nanokernel_semaphore
-   :project: Zephyr
-   :content-only:
-
-LIFOs
-=====
-
-.. doxygengroup:: nanokernel_lifo
-   :project: Zephyr
-   :content-only:
-
-FIFOs
-=====
-
-.. doxygengroup:: nanokernel_fifo
-   :project: Zephyr
-   :content-only:
-
-Stacks
-======
-
-.. doxygengroup:: nanokernel_stack
-   :project: Zephyr
-   :content-only:
-
-Timers
-======
-
-.. doxygengroup:: nanokernel_timer
-   :project: Zephyr
-   :content-only:
-
-Kernel Event Logger
--------------------
-
-.. doxygengroup:: nanokernel_event_logger
-   :project: Zephyr
-   :content-only:
-
-Microkernel
-***********
 
 Events
-======
+******
 
 .. doxygengroup:: microkernel_event
    :project: Zephyr
    :content-only:
 
 FIFOs
-=====
+*****
 
 .. doxygengroup:: microkernel_fifo
    :project: Zephyr
    :content-only:
 
 Pipes
-=====
+*****
 
 .. doxygengroup:: microkernel_pipe
    :project: Zephyr
    :content-only:
 
 Interrupt Services
-==================
+******************
 
 .. doxygengroup:: microkernel_irq
    :project: Zephyr
    :content-only:
 
 Mailboxes
-=========
+*********
 
 .. doxygengroup:: microkernel_mailbox
    :project: Zephyr
    :content-only:
 
 Memory Maps
-===========
+***********
 
 .. doxygengroup:: microkernel_memorymap
    :project: Zephyr
    :content-only:
 
 Mutexes
-=======
+*******
 
 .. doxygengroup:: microkernel_mutex
    :project: Zephyr
    :content-only:
 
 Semaphores
-==========
+**********
 
 .. doxygengroup:: microkernel_semaphore
    :project: Zephyr
    :content-only:
 
 Timers
-======
+******
 
 .. doxygengroup:: microkernel_timer
    :project: Zephyr
    :content-only:
 
 Tasks
-=====
+*****
 
 .. doxygengroup:: microkernel_task
    :project: Zephyr

doc/api/nanokernel_api.rst

@@ -0,0 +1,58 @@
+.. nanokernel_api:
+
+Nanokernel APIs
+###############
+
+.. contents::
+   :depth: 1
+   :local:
+   :backlinks: top
+
+Fibers
+******
+
+.. doxygengroup:: nanokernel_fiber
+   :project: Zephyr
+   :content-only:
+
+Semaphores
+**********
+
+.. doxygengroup:: nanokernel_semaphore
+   :project: Zephyr
+   :content-only:
+
+LIFOs
+*****
+
+.. doxygengroup:: nanokernel_lifo
+   :project: Zephyr
+   :content-only:
+
+FIFOs
+*****
+
+.. doxygengroup:: nanokernel_fifo
+   :project: Zephyr
+   :content-only:
+
+Stacks
+******
+
+.. doxygengroup:: nanokernel_stack
+   :project: Zephyr
+   :content-only:
+
+Timers
+******
+
+.. doxygengroup:: nanokernel_timer
+   :project: Zephyr
+   :content-only:
+
+Kernel Event Logger
+*******************
+
+.. doxygengroup:: nanokernel_event_logger
+   :project: Zephyr
+   :content-only:

doc/index.rst

@@ -21,6 +21,7 @@ Developer Guides
    reference/kbuild/kbuild.rst
    application/application.rst
    board/board.rst
+   api/api.rst
    collaboration/collaboration
 
 Reference Guides
@@ -29,7 +30,6 @@ Reference Guides
 .. toctree::
    :maxdepth: 1
 
-   reference/api.rst
    reference/kconfig/index.rst
 
 Indices and tables