Introducing the user content

Moving the user content down the mandatory directory path.

Change-Id: Icccf00cb22eab01c9ae7626f0997b9c362471e4d
Partial-Bug: 1702142

CONTRIBUTING.rst

@@ -69,7 +69,7 @@ To run the functional tests, use::
     tox -e func
 
 Once you have added new state or transition into inspection state machine, you
-should regenerate :ref:`state_machine_diagram` with::
+should regenerate :ref:`State machine diagram <state_machine_diagram>` with::
 
     tox -e genstates
 

doc/source/index.rst

@@ -1,16 +1,5 @@
 .. include:: ../../README.rst
 
-User Guide
-===========
-
-.. toctree::
-  :maxdepth: 2
-
-  Workflow <workflow>
-  Usage <usage>
-  HTTP API <http-api>
-  Troubleshooting <troubleshooting>
-
 Install
 =======
 
@@ -28,6 +17,14 @@ Contributor
 
    contributor/index
 
+User
+====
+
+.. toctree::
+  :maxdepth: 2
+
+  user/index
+
 Indices and tables
 ==================
 

doc/source/install/index.rst

@@ -339,7 +339,7 @@ If you are upgrading from **ironic-inspector** version 2.1.0 or lower:
     ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf upgrade
 
 If you are upgrading from a git master install of the **ironic-inspector**
-after :ref:`rules` were introduced:
+after :ref:`rules <introspection_rules>` were introduced:
 ::
 
     ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf stamp --revision d588418040d

doc/source/user/http-api.rst

@@ -1,8 +1,8 @@
-.. _api:
-
 HTTP API
 --------
 
+.. _http_api:
+
 By default **ironic-inspector** listens on ``0.0.0.0:5050``, port
 can be changed in configuration. Protocol is JSON over HTTP.
 
@@ -153,7 +153,7 @@ Response:
 Introspection Rules
 ~~~~~~~~~~~~~~~~~~~
 
-See :ref:`rules` for details.
+See :ref:`rules <introspection_rules>` for details.
 
 All these API endpoints require X-Auth-Token header with Keystone token for
 authentication.
@@ -162,8 +162,8 @@ authentication.
 
   Request body: JSON dictionary with keys:
 
-  * ``conditions`` rule conditions, see :ref:`rules`
+  * ``conditions`` rule conditions, see :ref:`rules <introspection_rules>`
-  * ``actions`` rule actions, see :ref:`rules`
+  * ``actions`` rule actions, see :ref:`rules <introspection_rules>`
   * ``description`` (optional) human-readable description
   * ``uuid`` (optional) rule UUID, autogenerated if missing
 
@@ -213,11 +213,11 @@ authentication.
   * 204 - OK
   * 404 - not found
 
-.. _ramdisk_callback:
-
 Ramdisk Callback
 ~~~~~~~~~~~~~~~~
 
+.. _ramdisk_callback:
+
 ``POST /v1/continue`` internal endpoint for the ramdisk to post back
 discovered data. Should not be used for anything other than implementing
 the ramdisk. Request body: JSON dictionary with at least these keys:
@@ -270,8 +270,8 @@ Optionally the following keys might be provided:
 
 .. note::
     This list highly depends on enabled plugins, provided above are
-    expected keys for the default set of plugins. See :ref:`plugins`
+    expected keys for the default set of plugins. See
-    for details.
+    :ref:`plugins <introspection_plugins>` for details.
 
 .. note::
     This endpoint is not expected to be versioned, though versioning will work

doc/source/user/index.rst

@@ -0,0 +1,34 @@
+User Guide
+==========
+
+How Ironic Inspector Works
+--------------------------
+
+.. toctree::
+  :maxdepth: 2
+
+  workflow
+
+How to use Ironic Inspector
+---------------------------
+
+.. toctree::
+  :maxdepth: 2
+
+  usage
+
+HTTP API Reference
+------------------
+
+.. toctree::
+  :maxdepth: 2
+
+  http-api
+
+Troubleshooting
+---------------
+
+.. toctree::
+  :maxdepth: 2
+
+  troubleshooting

doc/source/user/troubleshooting.rst

@@ -1,17 +1,17 @@
 Troubleshooting
-===============
+---------------
 
 Errors when starting introspection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * *Invalid provision state "available"*
 
-  In Kilo release with *python-ironicclient* 0.5.0 or newer Ironic
+  In Kilo release with *python-ironicclient* 0.5.0 or newer Ironic defaults to
-  defaults to reporting provision state ``AVAILABLE`` for newly enrolled
+  reporting provision state ``AVAILABLE`` for newly enrolled nodes.
-  nodes.  **ironic-inspector** will refuse to conduct introspection in
+  **ironic-inspector** will refuse to conduct introspection in this state, as
-  this state, as such nodes are supposed to be used by Nova for scheduling.
+  such nodes are supposed to be used by Nova for scheduling. See :ref:`node
-  See :ref:`node_states` for instructions on how to put nodes into
+  states <node_states>` for instructions on how to put nodes into the correct
-  the correct state.
+  state.
 
 Introspection times out
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -116,11 +116,11 @@ one.
 .. _devuser: http://docs.openstack.org/developer/diskimage-builder/elements/devuser/README.html
 .. _dynamic-login: http://docs.openstack.org/developer/diskimage-builder/elements/dynamic-login/README.html
 
-.. _ubuntu-dns:
-
 Troubleshooting DNS issues on Ubuntu
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. _ubuntu-dns:
+
 Ubuntu uses local DNS caching, so tries localhost for DNS results first
 before calling out to an external DNS server. When DNSmasq is installed and
 configured for use with ironic-inspector, it can cause problems by interfering

doc/source/user/usage.rst

@@ -1,9 +1,9 @@
-.. _usage:
-
 Usage
-=====
+-----
 
-Refer to :ref:`api` for information on the HTTP API.
+.. _usage_guide:
+
+Refer to :ref:`api <http_api>` for information on the HTTP API.
 Refer to the `client documentation`_ for information on how to use CLI and
 Python library.
 
@@ -18,11 +18,11 @@ drivers, please refer to `Ironic inspection documentation`_ for details.
 
 .. _Ironic inspection documentation: http://docs.openstack.org/developer/ironic/deploy/inspection.html
 
-.. _node_states:
-
 Node States
 ~~~~~~~~~~~
 
+.. _node_states:
+
 * The nodes should be moved to ``MANAGEABLE`` provision state before
   introspection (requires *python-ironicclient* of version 0.5.0 or newer)::
 
@@ -38,11 +38,11 @@ Node States
     before Nova becomes aware of available nodes after issuing this command.
     Use ``nova hypervisor-stats`` command output to check it.
 
-.. _rules:
-
 Introspection Rules
 ~~~~~~~~~~~~~~~~~~~
 
+.. _introspection_rules:
+
 Inspector supports a simple JSON-based DSL to define rules to run during
 introspection. Inspector provides an API to manage such rules, and will run
 them automatically after running all processing hooks.
@@ -51,8 +51,8 @@ A rule consists of conditions to check, and actions to run. If conditions
 evaluate to true on the introspection data, then actions are run on a node.
 
 Available conditions and actions are defined by plugins, and can be extended,
-see :ref:`contributing_link` for details. See :ref:`api` for specific calls
+see :ref:`contributing_link` for details. See :ref:`api <http_api>` for
-to define introspection rules.
+specific calls to define introspection rules.
 
 Conditions
 ^^^^^^^^^^
@@ -130,11 +130,11 @@ from introspection, it's using `python string formatting notation
     {"action": "set-attribute", "path": "/driver_info/ipmi_address",
      "value": "{data[inventory][bmc_address]}"}
 
-.. _plugins:
-
 Plugins
 ~~~~~~~
 
+.. _introspection_plugins:
+
 **ironic-inspector** heavily relies on plugins for data processing. Even the
 standard functionality is largely based on plugins. Set ``processing_hooks``
 option in the configuration file to change the set of plugins to be run on
@@ -165,7 +165,7 @@ needed:
 
 ``ramdisk_error``
     reports error, if ``error`` field is set by the ramdisk, also optionally
-    stores logs from ``logs`` field, see :ref:`api` for details.
+    stores logs from ``logs`` field, see :ref:`api <http_api>` for details.
 ``capabilities``
     detect node capabilities: CPU, boot mode, etc. See `Capabilities
     Detection`_ for more details.
@@ -225,13 +225,13 @@ file, to the Ironic driver you want).
 
 The ``enroll`` hook will also set the ``ipmi_address`` property on the new
 node, if its available in the introspection data we received,
-see :ref:`ramdisk_callback`.
+see :ref:`ramdisk_callback <ramdisk_callback>`.
 
 Once the ``enroll`` hook is finished, **ironic-inspector** will process the
 introspection data in the same way it would for an identified node. It runs
-the processing :ref:`plugins`, and after that it runs introspection
+the processing :ref:`plugins <introspection_plugins>`, and after that it runs
-rules, which would allow for more customisable node configuration,
+introspection rules, which would allow for more customisable node
-see :ref:`rules`.
+configuration, see :ref:`rules <introspection_rules>`.
 
 A rule to set a node's Ironic driver to the ``agent_ipmitool`` driver and
 populate the required driver_info for that driver would look like::

doc/source/user/workflow.rst

@@ -1,5 +1,8 @@
+How Ironic Inspector Works
+==========================
+
 Workflow
-========
+--------
 
 Usual hardware introspection flow is as follows:
 
@@ -7,10 +10,10 @@ Usual hardware introspection flow is as follows:
   Power management credentials should be provided to Ironic at this step.
 
 * Nodes are put in the correct state for introspection as described in
-  :ref:`node_states`.
+  :ref:`node states <node_states>`.
 
 * Operator sends nodes on introspection using **ironic-inspector** API or CLI
-  (see :ref:`usage`).
+  (see :ref:`usage <usage_guide>`).
 
 * On receiving node UUID **ironic-inspector**:
 
@@ -52,28 +55,29 @@ Usual hardware introspection flow is as follows:
     the ``keep_ports`` option should be also set to ``all``. This will ensure
     no manually added ports will be deleted.
 
-* Separate API (see :ref:`usage` and :ref:`api`) can be used to query
+.. _Ironic inspection documentation: http://docs.openstack.org/developer/ironic/deploy/inspection.html
-  introspection results for a given node.
+
+* Separate API (see :ref:`usage <usage_guide>` and :ref:`api <http_api>`) can
+  be used to query introspection results for a given node.
 
 * Nodes are put in the correct state for deploying as described in
-  :ref:`node_states`.
+  :ref:`node states <node_states>`.
 
 Starting DHCP server and configuring PXE boot environment is not part of this
 package and should be done separately.
 
-.. _state_machine_diagram:
-
 State machine diagram
-=====================
+---------------------
+
+.. _state_machine_diagram:
 
 The diagram below shows the introspection states that an **ironic-inspector**
 FSM goes through during the node introspection, discovery and reprocessing.
 The diagram also shows events that trigger state transitions.
 
-.. figure:: ./images/states.svg
+.. figure:: ../images/states.svg
    :width: 660px
    :align: center
    :alt: ironic-inspector state machine diagram
 
-.. _Ironic inspection documentation: https://docs.openstack.org/developer/ironic/deploy/inspection.html
 .. _Ironic: https://wiki.openstack.org/wiki/Ironic