doc: Restructure

Restructure the documentation to be split into `User Information` and
`Developer Information`, and split the how to guides into their
corresponding section.

28 files changed, 122 insertions, 86 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 4258e8b7..5cc42553 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -95,8 +95,8 @@ language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['../build', 'developer_reference', 'user_reference',
-                    'how_tos', 'run_config']
+exclude_patterns = ['../build', 'developer_information',
+                    'user_information', 'run_config']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -314,7 +314,8 @@ def setup(app):
     generate_target_documentation('plugins')
     generate_run_config_documentation('run_config')
     generate_meta_config_documentation('run_config')
-    generate_instrument_method_map(os.path.join('developer_reference', 'instrument_method_map.rst'))
+    generate_instrument_method_map(os.path.join('developer_information', 'developer_reference',
+                                                'instrument_method_map.rst'))
     app.add_object_type('confval', 'confval',
                         objname='configuration value',
                         indextemplate='pair: %s; configuration value')
diff --git a/doc/source/developer_information.rst b/doc/source/developer_information.rst
new file mode 100644
index 00000000..ff7cb99b
--- /dev/null
+++ b/doc/source/developer_information.rst
@@ -0,0 +1,11 @@
+=====================
+Developer Information
+=====================
+
+.. contents:: Contents
+   :depth: 4
+   :local:
+
+
+.. include:: developer_information/how_to.rst
+.. include:: developer_information/developer_reference.rst
diff --git a/doc/source/developer_information/developer_reference.rst b/doc/source/developer_information/developer_reference.rst
new file mode 100644
index 00000000..47f674af
--- /dev/null
+++ b/doc/source/developer_information/developer_reference.rst
@@ -0,0 +1,28 @@
+.. _developer_reference:
+
+********************
+Developer Reference
+********************
+
+.. contents::
+   :depth: 3
+   :local:
+
+
+.. include:: developer_information/developer_reference/execution_model.rst
+
+-----------------
+
+.. include:: developer_information/developer_reference/writing_plugins.rst
+
+-----------------
+
+.. include:: developer_information/developer_reference/contributing.rst
+
+-----------------
+
+.. include:: developer_information/developer_reference/revent.rst
+
+-----------------
+
+.. include:: developer_information/developer_reference/serialization.rst
diff --git a/doc/source/developer_reference/WA_Execution.svg b/doc/source/developer_information/developer_reference/WA_Execution.svg
index a886e6e4..a886e6e4 100644
--- a/doc/source/developer_reference/WA_Execution.svg
+++ b/doc/source/developer_information/developer_reference/WA_Execution.svg
diff --git a/doc/source/developer_reference/WA_Signal_Dispatch.svg b/doc/source/developer_information/developer_reference/WA_Signal_Dispatch.svg
index c8ee2acc..c8ee2acc 100644
--- a/doc/source/developer_reference/WA_Signal_Dispatch.svg
+++ b/doc/source/developer_information/developer_reference/WA_Signal_Dispatch.svg
diff --git a/doc/source/developer_reference/contributing.rst b/doc/source/developer_information/developer_reference/contributing.rst
index dd25bd6c..dd25bd6c 100644
--- a/doc/source/developer_reference/contributing.rst
+++ b/doc/source/developer_information/developer_reference/contributing.rst
diff --git a/doc/source/developer_reference/execution_model.rst b/doc/source/developer_information/developer_reference/execution_model.rst
index 0efadb34..ab3e28c5 100644
--- a/doc/source/developer_reference/execution_model.rst
+++ b/doc/source/developer_information/developer_reference/execution_model.rst
@@ -6,7 +6,7 @@ Execution Model
 
 At the high level, the execution model looks as follows:
 
-.. image:: developer_reference/WA_Execution.svg
+.. image:: developer_information/developer_reference/WA_Execution.svg
    :scale: 100 %
 
 After some initial setup, the framework initializes the device, loads and
@@ -149,7 +149,7 @@ is also sent just after stage has been completed. The diagram also lists the
 conditional signals that can be sent at any time during execution if something
 unexpected happens, for example an error occurs or the user aborts the run.
 
-.. image:: developer_reference/WA_Signal_Dispatch.svg
+.. image:: developer_information/developer_reference/WA_Signal_Dispatch.svg
    :scale: 100 %
 
 See Also
diff --git a/doc/source/developer_reference/revent.rst b/doc/source/developer_information/developer_reference/revent.rst
index faea285c..faea285c 100644
--- a/doc/source/developer_reference/revent.rst
+++ b/doc/source/developer_information/developer_reference/revent.rst
diff --git a/doc/source/developer_reference/serialization.rst b/doc/source/developer_information/developer_reference/serialization.rst
index 64859e69..64859e69 100644
--- a/doc/source/developer_reference/serialization.rst
+++ b/doc/source/developer_information/developer_reference/serialization.rst
diff --git a/doc/source/developer_reference/writing_plugins.rst b/doc/source/developer_information/developer_reference/writing_plugins.rst
index d079b6bb..27e0457b 100644
--- a/doc/source/developer_reference/writing_plugins.rst
+++ b/doc/source/developer_information/developer_reference/writing_plugins.rst
@@ -1015,7 +1015,7 @@ Below is a simple instrument that measures the execution time of a workload::
             context.add_metric('execution_time', execution_time, 'seconds')
 
 
-.. include:: developer_reference/instrument_method_map.rst
+.. include:: developer_information/developer_reference/instrument_method_map.rst
 
 .. _adding-an-output-processor:
 
diff --git a/doc/source/developer_information/how_to.rst b/doc/source/developer_information/how_to.rst
new file mode 100644
index 00000000..094c9ae2
--- /dev/null
+++ b/doc/source/developer_information/how_to.rst
@@ -0,0 +1,9 @@
+*******
+How Tos
+*******
+
+.. contents:: Contents
+   :depth: 4
+   :local:
+
+.. include:: developer_information/how_tos/adding_plugins.rst
diff --git a/doc/source/how_tos/developers/adding_plugins.rst b/doc/source/developer_information/how_tos/adding_plugins.rst
index b47407f2..b47407f2 100644
--- a/doc/source/how_tos/developers/adding_plugins.rst
+++ b/doc/source/developer_information/how_tos/adding_plugins.rst
diff --git a/doc/source/how_to.rst b/doc/source/how_to.rst
deleted file mode 100644
index 8ad5d422..00000000
--- a/doc/source/how_to.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-========
-How Tos
-========
-
-.. contents:: Contents
-   :depth: 4
-   :local:
-
-Users
-""""""
-
-.. include:: how_tos/users/agenda.rst
-.. include:: how_tos/users/device_setup.rst
-.. include:: how_tos/users/revent.rst
-
-Developers
-"""""""""""
-
-.. include:: how_tos/developers/adding_plugins.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 0be64e1c..4169eada 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -37,32 +37,14 @@ User Information
 ================
 
 This section lists general usage documentation. If you're new to WA3, it is
-recommended you start with the :doc:`user_guide` page. This section also contains
+recommended you start with the :ref:`User Guide <user-guide>` page. This section also contains
 installation and configuration guides.
 
 .. toctree::
-   :maxdepth: 2
-
-   installation
-   user_guide
-   user_reference
-
-
-How To Guides
-===============
-
-.. toctree::
    :maxdepth: 3
 
-   how_to
-
-FAQ
-====
-
-.. toctree::
-   :maxdepth: 2
+   user_information
 
-   faq
 
 .. _in-depth:
 
@@ -73,9 +55,9 @@ This section contains more advanced topics, such how to write your own Plugins
 and detailed descriptions of how WA functions under the hood.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
-   developer_reference
+   developer_information
 
 
 References
@@ -87,7 +69,6 @@ References
    plugins
    glossary
 
-
 API
 ===
 
@@ -96,9 +77,10 @@ API
 
     api
 
-.. Indices and tables
-.. ==================
+FAQ
+====
 
-.. .. * :ref:`genindex`
-.. .. * :ref:`modindex`
-.. * :ref:`search`
+.. toctree::
+   :maxdepth: 2
+
+   faq
diff --git a/doc/source/user_information.rst b/doc/source/user_information.rst
new file mode 100644
index 00000000..5a24e62a
--- /dev/null
+++ b/doc/source/user_information.rst
@@ -0,0 +1,12 @@
+================
+User Information
+================
+
+.. contents:: Contents
+   :depth: 4
+   :local:
+
+.. include:: user_information/installation.rst
+.. include:: user_information/user_guide.rst
+.. include:: user_information/how_to.rst
+.. include:: user_information/user_reference.rst
diff --git a/doc/source/user_information/how_to.rst b/doc/source/user_information/how_to.rst
new file mode 100644
index 00000000..ca590f2b
--- /dev/null
+++ b/doc/source/user_information/how_to.rst
@@ -0,0 +1,11 @@
+*******
+How Tos
+*******
+
+.. contents:: Contents
+   :depth: 4
+   :local:
+
+.. include:: user_information/how_tos/agenda.rst
+.. include:: user_information/how_tos/device_setup.rst
+.. include:: user_information/how_tos/revent.rst
diff --git a/doc/source/how_tos/users/agenda.rst b/doc/source/user_information/how_tos/agenda.rst
index a206b0a9..a206b0a9 100644
--- a/doc/source/how_tos/users/agenda.rst
+++ b/doc/source/user_information/how_tos/agenda.rst
diff --git a/doc/source/how_tos/users/device_setup.rst b/doc/source/user_information/how_tos/device_setup.rst
index d8a1ca7a..d8a1ca7a 100644
--- a/doc/source/how_tos/users/device_setup.rst
+++ b/doc/source/user_information/how_tos/device_setup.rst
diff --git a/doc/source/how_tos/users/revent.rst b/doc/source/user_information/how_tos/revent.rst
index b3b610d6..b3b610d6 100644
--- a/doc/source/how_tos/users/revent.rst
+++ b/doc/source/user_information/how_tos/revent.rst
diff --git a/doc/source/installation.rst b/doc/source/user_information/installation.rst
index 45089926..da776a09 100644
--- a/doc/source/installation.rst
+++ b/doc/source/user_information/installation.rst
@@ -1,12 +1,13 @@
-============
+.. _installation:
+
+************
 Installation
-============
+************
 
 .. contents:: Contents
    :depth: 2
    :local:
 
-------------------------------------------------------------
 
 .. module:: wa
 
diff --git a/doc/source/user_guide.rst b/doc/source/user_information/user_guide.rst
index a9a32934..596ebc26 100644
--- a/doc/source/user_guide.rst
+++ b/doc/source/user_information/user_guide.rst
@@ -1,6 +1,8 @@
-==========
+.. _user-guide:
+
+**********
 User Guide
-==========
+**********
 
 This guide will show you how to quickly start running workloads using
 Workload Automation 3.
@@ -16,7 +18,7 @@ Install
 =======
 
 .. note:: This is a quick summary. For more detailed instructions, please see
-          the :doc:`installation` section.
+          the :ref:`installation` section.
 
 Make sure you have Python 2.7 and a recent Android SDK with API level 18 or above
 installed on your system. A complete install of the Android SDK is required, as
diff --git a/doc/source/user_information/user_reference.rst b/doc/source/user_information/user_reference.rst
new file mode 100644
index 00000000..34878d96
--- /dev/null
+++ b/doc/source/user_information/user_reference.rst
@@ -0,0 +1,23 @@
+.. _user_reference:
+
+***************
+User Reference
+***************
+
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+
+.. include:: user_information/user_reference/configuration.rst
+
+-------------------
+
+.. include:: user_information/user_reference/invocation.rst
+
+-------------------
+
+.. include:: user_information/user_reference/output_directory.rst
+
+
+
diff --git a/doc/source/user_reference/agenda.rst b/doc/source/user_information/user_reference/agenda.rst
index 1bac5f81..1bac5f81 100644
--- a/doc/source/user_reference/agenda.rst
+++ b/doc/source/user_information/user_reference/agenda.rst
diff --git a/doc/source/user_reference/configuration.rst b/doc/source/user_information/user_reference/configuration.rst
index 12b6c412..9fb6e72c 100644
--- a/doc/source/user_reference/configuration.rst
+++ b/doc/source/user_information/user_reference/configuration.rst
@@ -4,7 +4,7 @@
 Configuration
 =============
 
-.. include:: user_reference/agenda.rst
+.. include:: user_information/user_reference/agenda.rst
 
 ---------------------
 
@@ -74,7 +74,7 @@ various assets when it starts.
 
 ---------------------
 
-.. include:: user_reference/runtime_parameters.rst
+.. include:: user_information/user_reference/runtime_parameters.rst
 
 ---------------------
 
diff --git a/doc/source/user_reference/invocation.rst b/doc/source/user_information/user_reference/invocation.rst
index 6c1762e2..6c1762e2 100644
--- a/doc/source/user_reference/invocation.rst
+++ b/doc/source/user_information/user_reference/invocation.rst
diff --git a/doc/source/user_reference/output_directory.rst b/doc/source/user_information/user_reference/output_directory.rst
index e68b94a1..e68b94a1 100644
--- a/doc/source/user_reference/output_directory.rst
+++ b/doc/source/user_information/user_reference/output_directory.rst
diff --git a/doc/source/user_reference/runtime_parameters.rst b/doc/source/user_information/user_reference/runtime_parameters.rst
index f1ca0541..f1ca0541 100644
--- a/doc/source/user_reference/runtime_parameters.rst
+++ b/doc/source/user_information/user_reference/runtime_parameters.rst
diff --git a/doc/source/user_reference.rst b/doc/source/user_reference.rst
deleted file mode 100644
index a0dd9f35..00000000
--- a/doc/source/user_reference.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-.. _user_reference:
-
-===============
-User Reference
-===============
-
-
-.. contents:: Contents
-   :depth: 2
-   :local:
-
----------------------------------------------------------------
-
-.. include:: user_reference/configuration.rst
-
--------------------
-
-.. include:: user_reference/invocation.rst
-
--------------------
-
-.. include:: user_reference/output_directory.rst
-
-
-