doc: reorganize documentation

We've been expanding documentation, and now need to organize things a bit
cleaner and separate content into new major folders: Introduction, Getting
Started, User Guides, Developer Guides, Tutorials, and Release notes..

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

doc/tutorials/docbuild.rst

@@ -0,0 +1,220 @@
+.. _acrn_doc:
+
+ACRN documentation generation
+#############################
+
+These instructions will walk you through generating the Project ACRN's
+documentation and publishing it to https://projectacrn.github.io.
+You can also use these instructions to generate the ARCN documentation
+on your local system.
+
+Documentation overview
+**********************
+
+Project ACRN content is written using the reStructuredText markup
+language (.rst file extension) with Sphinx extensions, and processed
+using Sphinx to create a formatted stand-alone website. Developers can
+view this content either in its raw form as .rst markup files, or you
+can generate the HTML content and view it with a web browser directly on
+your workstation.
+
+You can read details about `reStructuredText`_, and `Sphinx`_ from
+their respective websites.
+
+The project's documentation contains the following items:
+
+* ReStructuredText source files used to generate documentation found at the
+  http://projectacrn.github.io website. All of the reStructuredText sources
+  are found in this acrn-documentation repo.
+
+* Doxygen-generated material used to create all API-specific documents
+  found at http://projectacrn.github.io/api/.  Source files from the
+  acrn-hypervisor/hypervisor and acrn-hypervisor/devicemodel repos are also used to access the
+  header files for the the public APIs, but more about that later.
+
+The reStructuredText files are processed by the Sphinx documentation system,
+and make use of the breathe extension for including the doxygen-generated API
+material.
+
+
+Set up the documentation working folders
+****************************************
+
+You'll need git installed to get the working folders set up:
+
+* For an Ubuntu development system use:
+
+  .. code-block:: bash
+
+     sudo apt-get install git
+
+* For a Fedora development system use
+
+  .. code-block:: bash
+
+     sudo dnf install git
+
+We use the source header files to generate API docs and we use github.io
+for publishing the generated documentation.
+Here's the recommended folder setup for documentation contributions and
+generation:
+
+.. code-block: none
+
+   projectacrn/
+      acrn-hypervisor/
+         devicemodel/
+         doc/
+         hypervisor/
+
+The parent projectacrn folder is there because we'll also be creating a
+publishing area later in these steps.  It's best if the acrn-hypervisor
+folder is an ssh clone of your personal fork of the upstream project
+repos (though https clones work too):
+
+#. Use your browser to visit https://github.com/projectacrn and do a
+   fork of the **acrn-hypervisor** repo to your personal GitHub account.)
+
+   .. image:: images/acrn-doc-fork.png
+      :align: center
+
+#. At a command prompt, create the working folder and clone the acrn-hypervisor
+   repository to your local computer (and if you have publishing rights, the
+   projectacrn.github.io repo).  If you don't have publishing rights
+   you'll still be able to generate the docs locally, but not publish them:
+
+   .. code-block:: bash
+
+      cd ~
+      mkdir projectacrn && cd projectacrn
+      git clone git@github.com:<github-username>/projectacrn/acrn-hypervisor.git
+
+#. For the cloned local repos, tell git about the upstream repo:
+
+   .. code-block:: bash
+
+      cd acrn-hypervisor
+      git remote add upstream git@github.com:projectacrn/acrn-hypervisor.git
+
+#. If you haven't do so already, be sure to configure git with your name
+   and email address for the signed-off-by line in your commit messages:
+
+   .. code-block:: bash
+
+      git config --global user.name "David Developer"
+      git config --global user.email "david.developer@company.com"
+
+Installing the documentation tools
+**********************************
+
+Our documentation processing has been tested to run with:
+
+* Python 3.6.3
+* Doxygen version 1.8.13
+* Sphinx version 1.7.5
+* Breathe version 4.9.1
+* docutils version 0.14
+* sphinx_rtd_theme version 0.4.0
+
+Depending on your Linux version, install the needed tools:
+
+* For Ubuntu use:
+
+  .. code-block:: bash
+
+     sudo apt-get install doxygen python3-pip \
+       python3-wheel make graphviz
+
+* For Fedora use:
+
+  .. code-block:: bash
+
+     sudo dnf install doxygen python3-pip python3-wheel make graphviz
+
+And for either Linux environment, install the remaining python-based
+tools:
+
+.. code-block:: bash
+
+   cd ~/projectacrn/acrn-hypervisor/doc
+   pip3 install --user -r scripts/requirements.txt
+
+And with that you're ready to generate the documentation.
+
+Documentation presentation theme
+********************************
+
+Sphinx supports easy customization of the generated documentation
+appearance through the use of themes.  Replace the theme files and do
+another ``make html`` and the output layout and style is changed.
+The ``read-the-docs`` theme is installed as part of the
+``requirements.txt`` list above.
+
+Running the documentation processors
+************************************
+
+The acrn-hypervisor/doc directory has all the .rst source files, extra tools, and Makefile for
+generating a local copy of the ACRN technical documentation.
+
+.. code-block:: bash
+
+   cd ~/projectacrn/acrn-hypervisor/doc
+   make html
+
+Depending on your development system, it will take about 15 seconds to
+collect and generate the HTML content.  When done, you can view the HTML
+output with your browser started at ``~/projectacrn/acrn-hypervisor/doc/_build/html/index.html``
+
+Publishing content
+******************
+
+If you have merge rights to the projectacrn repo called
+projectacrn.github.io, you can update the public project documentation
+found at https://projectacrn.github.io.
+
+You'll need to do a one-time clone of the upstream repo (we publish
+directly to the upstream repo rather than to a personal forked copy):
+
+.. code-block:: bash
+
+   cd ~/projectacrn
+   git clone git@github.com:projectacrn/projectacrn.github.io.git
+
+Then, after you've verified the generated HTML from ``make html`` looks
+good, you can push directly to the publishing site with:
+
+.. code-block:: bash
+
+   make publish
+
+This will delete everything in the publishing repo's **latest** folder
+(in case the new version has
+deleted files) and push a copy of the newly-generated HTML content
+directly to the GitHub pages publishing repo.  The public site at
+https://projectacrn.github.io will be updated (nearly) immediately
+so it's best to verify the locally generated html before publishing.
+
+Filtering expected warnings
+***************************
+
+Alas, there are some known issues with the doxygen/Sphinx/Breathe
+processing that generates warnings for some constructs, in particular
+around unnamed structures in nested unions or structs.
+While these issues are being considered for fixing in
+Sphinx/Breathe, we've added a post-processing filter on the output of
+the documentation build process to check for "expected" messages from the
+generation process output.
+
+The output from the Sphinx build is processed by the python script
+``scripts/filter-known-issues.py`` together with a set of filter
+configuration files in the ``.known-issues/doc`` folder.  (This
+filtering is done as part of the ``Makefile``.)
+
+If you're contributing components included in the ACRN API
+documentation and run across these warnings, you can include filtering
+them out as "expected" warnings by adding a conf file to the
+``.known-issues/doc`` folder, following the example of other conf files
+found there.
+
+.. _reStructuredText: http://sphinx-doc.org/rest.html
+.. _Sphinx: http://sphinx-doc.org/

doc/tutorials/graphviz.rst

@@ -0,0 +1,118 @@
+.. graphviz-examples:
+
+Drawings using graphviz
+#######################
+
+We support using the Sphinx `graphviz extension`_ for creating simple
+graphs and line drawings using the dot language.  The advantage of using
+graphviz for drawings is that source for a drawing is a text file that
+can be edited and maintained in the repo along with the documentation.
+
+.. _graphviz extension: http://graphviz.gitlab.io
+
+These source ``.dot`` files are generally kept separate from the document itself,
+and included by using a graphviz directive:
+
+.. code-block:: none
+
+   .. graphviz:: images/boot-flow.dot
+      :name: boot-flow-example
+      :align: center
+      :caption: ACRN Hypervisor Boot Flow
+
+Where the boot-flow.dot file contains the drawing commands:
+
+.. literalinclude:: images/boot-flow.dot
+
+and the generated output would appear as this:
+
+.. graphviz:: images/boot-flow.dot
+  :name: boot-flow-example
+  :align: center
+  :caption: ACRN Hypervisor Boot Flow
+
+
+Let's look at some more examples and then we'll get into more details
+about the dot language and drawing options.
+
+Simple directed graph
+*********************
+
+For simple drawings with shapes and lines, you can put the graphviz
+commands in the content block for the directive. For example for a
+simple directed graph (digraph) with two nodes connected by an arrow,
+you can write:
+
+
+.. code-block:: none
+
+    .. graphviz::
+
+       digraph {
+          "a" -> "b"
+       }
+
+and get this:
+
+.. graphviz::
+
+   digraph {
+      "a" -> "b"
+   }
+
+
+You can change the graph layout (from top-to-bottom to left-to-right), node
+shapes (rectangles, circles, house, star, etc.), style (filled, rounded),
+and colors, along with the text displayed in the node, and the resulting
+image placement on the page (centered):
+
+.. literalinclude:: images/circle-square.dot
+
+.. graphviz:: images/circle-square.dot
+   :align: center
+
+You can use the `standard HTML color names`_ or use RGB values for
+colors, as shown.
+
+.. _standard HTML color names:
+   https://www.w3schools.com/colors/colors_hex.asp
+
+Adding edge labels
+******************
+
+Here's an example of a drawing with labels on the edges (arrows)
+between nodes. We also show how to change the default attributes for all
+nodes and edges within this graph:
+
+.. literalinclude:: images/node-shape-edges.dot
+
+.. graphviz:: images/node-shape-edges.dot
+   :align: center
+
+Tables
+******
+
+For nodes with a ``record`` shape attribute, the text of the label is
+presented in a table format:  a vertical bar ``|`` starts a new row or
+column and curly braces ``{ ... }`` specify a new row (if you're in a
+column) or a new column (if you're in a row).  For example:
+
+.. literalinclude:: images/record.dot
+
+.. graphviz:: images/record.dot
+   :align: center
+
+Note that you can also specify the horizontal alignment of text using escape
+sequences ``\n``, ``\l`` and ``\r`` that divide the label into lines, centered,
+left-justified, and right-justified, respectively.
+
+Finite-State Machine
+********************
+
+Here's an example of using graphviz for definine a finite-state machine
+for pumping gas:
+
+.. literalinclude:: images/gaspump.dot
+
+.. graphviz:: images/gaspump.dot
+   :align: center

doc/tutorials/images/boot-flow.dot

@@ -0,0 +1,6 @@
+digraph G {
+   rankdir=LR;
+   bgcolor="transparent";
+   UEFI -> "acrn.efi" -> "OS\nBootloader" ->
+     "SOS\nKernel" -> "ACRN\nDevice Model" -> "Virtual\nBootloader";
+}

doc/tutorials/images/circle-square.dot

@@ -0,0 +1,9 @@
+digraph {
+   bgcolor="transparent"; rankdir=LR;
+   { a [shape=circle height="1" style=filled color=AntiqueWhite
+        label="Circle\nLabel"]
+     b [shape=box height="1" width="1" style="rounded,filled"
+        color="#F080F0" label="Square\nLabel"]
+   }
+   a -> b
+}

doc/tutorials/images/gaspump.dot

@@ -0,0 +1,11 @@
+digraph gaspump {
+        rankdir=LR;
+        node [shape = circle;];
+        edge [color = grey; fontsize=10];
+        S0 -> S1 [ label = "Lift Nozzle" ]
+        S1 -> S0 [ label = "Replace Nozzle" ]
+        S1 -> S2 [ label = "Authorize Pump" ]
+        S2 -> S0 [ label = "Replace Nozzle" ]
+        S2 -> S3 [ label = "Pull Trigger" ]
+        S3 -> S2 [ label = "Release Trigger" ]
+}

doc/tutorials/images/node-shape-edges.dot

@@ -0,0 +1,8 @@
+digraph {
+   bgcolor=transparent; rankdir=LR;
+   node [shape="rectangle" style="filled" color="lightblue"]
+   edge [fontsize="12" fontcolor="grey"]
+
+   "acrnprobe" -> "telemetrics-client" [label="crashlog\npath"]
+   "telemetrics-client" -> "backend"   [label="log\ncontent"]
+}

doc/tutorials/images/record.dot

@@ -0,0 +1,4 @@
+digraph {
+   a [shape=record label="left | {above|middle|below} | <f1>right"]
+   b [shape=record label="{row1\l|row2\r|{row3\nleft|<f2>row3\nright}|row4}"]
+}

doc/tutorials/index.rst

@@ -0,0 +1,14 @@
+.. _tutorials:
+
+Tutorials
+#########
+
+Here are some technical notes that help explain how you can use
+and work with ACRN capabilities and its development environment.
+
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *