doc: Restructure

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

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',
+exclude_patterns = ['../build', 'developer_information',
-                    'how_tos', 'run_config']
+                    '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')

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

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

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

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:
 

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

doc/source/how_to.rst

@@ -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

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
+   user_information
 
-FAQ
-====
-
-.. toctree::
-   :maxdepth: 2
-
-   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`
+.. toctree::
-.. .. * :ref:`modindex`
+   :maxdepth: 2
-.. * :ref:`search`
+
+   faq

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

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

doc/source/user_information/installation.rst

@@ -1,12 +1,13 @@
-============
+.. _installation:
+
+************
 Installation
-============
+************
 
 .. contents:: Contents
    :depth: 2
    :local:
 
-------------------------------------------------------------
 
 .. module:: wa
 

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

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
+
+
+

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
 
 ---------------------
 

doc/source/user_reference.rst

@@ -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
-
-
-