doc: introduce final structure

Move guides and APIs into separate directories and cleanup naming
introducing index files rather than named section files.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>

.known-issues/doc/bluetooth.conf

@@ -3,7 +3,7 @@
 #
 # FIXME: all these should match the relative filename
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]bluetooth.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]$
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]bluetooth.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]$
 ^[ \t]*$
 ^[ \t]*\^$
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]$
@@ -15,7 +15,7 @@
 #
 # bt_gatt_discover_params unnamed struct definition
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]bluetooth.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]bluetooth.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
@@ -27,7 +27,7 @@
 #
 # Bluetooth GATT unnamed struct definition
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]bluetooth.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]bluetooth.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
@@ -39,7 +39,7 @@
 #
 # Bluetooth mesh unnamed struct definition
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]bluetooth.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]bluetooth.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]

.known-issues/doc/display.conf

@@ -4,7 +4,7 @@
 #
 # include
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]display_api.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]display_api.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]

.known-issues/doc/duplicate.conf

@@ -1,6 +1,6 @@
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]file_system.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]file_system[/\\]index.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]peripherals[/\\]dma.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]peripherals[/\\]dma.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]peripherals[/\\]sensor.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]peripherals[/\\]sensor.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.

.known-issues/doc/kernel.conf

@@ -1,24 +0,0 @@
-#
-# Kernel
-#
-#
-# include/kernel.h warnings
-#
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]kernel_api.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
-^[ \t]*
-^[ \t]*\^
-^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
-^[ \t]*
-^[ \t]*\^
-^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
-^[ \t]*
-^[ \t]*\^
-^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
-^[ \t]*
-^[ \t]*\^
-^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
-^[ \t]*
-^[ \t]*\^
-^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
-^.*k_poll_event.__unnamed__
-^[- \t]*\^

.known-issues/doc/misc.conf

@@ -4,7 +4,7 @@
 #
 # include
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]misc_api.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]misc_api.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]

.known-issues/doc/networking.conf

@@ -4,7 +4,7 @@
 #
 # include/net/net_ip.h warnings
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
@@ -19,7 +19,7 @@
 #
 # include/net/net_mgmt.h
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
@@ -31,7 +31,7 @@
 #
 # include/net/buf.h
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
@@ -43,7 +43,7 @@
 #
 # include/net/ieee802154.h
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
@@ -55,16 +55,16 @@
 #
 # include/net/net_context.h
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]networking[/\\]net_context.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]networking[/\\]net_context.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
 ^.*net_context.options
 ^[- \t]*\^
 #
 # include/net/net_stats.h
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]networking[/\\]net_stats.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]networking[/\\]net_stats.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
 ^.*net_stats_tc.[a-z]+
 ^[- \t]*\^
 #
 # stray duplicate definition warnings
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]networking[/\\]net_if.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]networking[/\\]net_if.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.

.known-issues/doc/uart.conf

@@ -1,7 +1,7 @@
 #
 # UART unnamed struct definition
 #doc/api/peripherals/uart.rst
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]peripherals[/\\]uart.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]peripherals[/\\]uart.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
@@ -14,7 +14,7 @@
 ^.*uart_device_config.__unnamed__.*
 ^[- \t]*\^
 #
-^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]peripherals[/\\]uart.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]peripherals[/\\]uart.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
 ^[ \t]*
 ^[ \t]*\^
 ^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]

doc/guides/documentation/index.rst

@@ -320,7 +320,7 @@ of the reST files.  The names of these replacement characters are the same as us
 entities used to insert characters in HTML, e.g., \™ and are defined in the
 file ``sphinx_build/substitutions.txt`` as listed here:
 
-.. literalinclude:: ../substitutions.txt
+.. literalinclude:: ../../substitutions.txt
    :language: rst
 
 We've kept the substitutions list small but others can be added as
@@ -390,13 +390,13 @@ Images
 
 Images are included in documentation by using an image directive::
 
-   .. image:: ../images/doc-gen-flow.png
+   .. image:: ../../images/doc-gen-flow.png
       :align: center
       :alt: alt text for the image
 
 or if you'd like to add an image caption, use::
 
-    .. figure:: ../images/doc-gen-flow.png
+    .. figure:: ../../images/doc-gen-flow.png
        :alt: image description
 
        Caption for the figure
@@ -435,7 +435,7 @@ are an allowed exception.
 zephyr-app-commands Directive
 *****************************
 
-.. include:: ../extensions/zephyr/application.py
+.. include:: ../../extensions/zephyr/application.py
    :start-line: 10
    :start-after: '''
    :end-before: '''

doc/guides/index.rst

@@ -0,0 +1,23 @@
+.. _user_guides:
+
+User and Developer Guides
+#########################
+
+.. toctree::
+   :maxdepth: 1
+
+   bluetooth/index.rst
+   c_library
+   ../README.rst
+   coccinelle.rst
+   code-relocation.rst
+   device_mgmt/index
+   device_mgmt/dfu
+   documentation/index
+   dts/index
+   kconfig/index
+   networking/index
+   porting/index
+   test/index
+   tracing/index
+   west/index

doc/index.rst

@@ -49,7 +49,7 @@ licensing, as described in :ref:`Zephyr_Licensing`.
 	       system, and then build and run a sample application.</p>
        </li>
        <li class="grid-item">
-	   <a href="contribute/index.html">
+	   <a href="contribute/">
 	       <img alt="" src=""/>
 	       <h2>Contribution Guidelines</h2>
 	   </a>
@@ -65,7 +65,7 @@ licensing, as described in :ref:`Zephyr_Licensing`.
 	       by Zephyr</p>
        </li>
        <li class="grid-item">
-	   <a href="reference.html">
+	   <a href="reference/">
 	       <img alt="" src=""/>
 	       <h2>API Reference</h2>
 	   </a>
@@ -86,7 +86,7 @@ licensing, as described in :ref:`Zephyr_Licensing`.
 	   <p>List if supported boards and platforms.</p>
        </li>
        <li class="grid-item">
-	   <a href="user_guides.html">
+	   <a href="guides/">
 	       <img alt="" src=""/>
 	       <h2>User and Developer Guides</h2>
 	   </a>
@@ -107,8 +107,8 @@ licensing, as described in :ref:`Zephyr_Licensing`.
    contribute/index.rst
    development_process/index.rst
    application/application.rst
-   reference.rst
-   user_guides.rst
+   reference/index.rst
+   guides/index.rst
    security/security.rst
    samples/samples.rst
    boards/boards.rst

doc/reference.rst

@@ -1,23 +0,0 @@
-.. _api_reference:
-
-API Reference
-#############
-
-.. toctree::
-   :maxdepth: 1
-
-   api/bluetooth/index.rst
-   reference/kconfig/index.rst
-   devices/drivers/drivers.rst
-   api/display_api
-   api/file_system
-   kernel/kernel.rst
-   subsystems/logging/index
-   api/misc_api
-   api/networking/index
-   api/peripherals/index.rst
-   subsystems/power_management.rst
-   subsystems/shell/shell
-   subsystems/storage.rst
-   subsystems/usb/usb.rst
-

doc/reference/index.rst

@@ -0,0 +1,23 @@
+.. _api_reference:
+
+API Reference
+#############
+
+.. toctree::
+   :maxdepth: 1
+
+   bluetooth/index.rst
+   kconfig/index.rst
+   drivers/index.rst
+   display/index.rst
+   file_system/index.rst
+   kernel/index.rst
+   logging/index.rst
+   misc/index
+   networking/index.rst
+   peripherals/index.rst
+   power_management/index.rst
+   shell/index.rst
+   storage/index.rst
+   usb/index.rst
+