doc: update doc guidlines for ACRN config options

Explain how ACRN configuration options are documented and generated

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

Tracked-On: #5911

doc/developer-guides/doc_guidelines.rst

@@ -653,6 +653,45 @@ This is the second instruction step.
    only one set of numbered steps is intended per document and the steps
    must be level 2 headings.
 
+Configuration Option Documentation
+**********************************
+
+Most of the ACRN documentation is maintained in ``.rst`` files found in the
+``doc/`` folder.  API documentation is maintained as Doxygen comments in the C
+header files (or as kerneldoc comments in the ``acrn-kernel`` repo headers),
+along with some prose documentation in ``.rst`` files. The ACRN configuration
+option documentation is created based on details maintained in schema definition
+files (``.xsd``) in the ``misc/config_tools/schema`` folder.  These schema
+definition files are used by the configuration tool to validate the XML scenario
+configuration files as well as to hold documentation about each option.  For
+example:
+
+.. code-block:: xml
+
+    <xs:element name="RELEASE" type="Boolean" default="n">
+      <xs:annotation>
+        <xs:documentation>Build an image for release (``y``) or debug (``n``).
+    In a **release** image, assertions are not enforced and debugging
+    features are disabled, including logs, serial console, and the
+    hypervisor shell.</xs:documentation>
+      </xs:annotation>
+    </xs:element>
+
+During the documentation ``make html`` processing, the documentation annotations
+in the ``.xsd`` files are extracted and transformed into restructureText using
+an XSLT transformation found in ``doc/scripts/configdoc.xsl``. The generated
+option documentation is organized and formatted to make it easy to created links
+to specific option descriptions using an ``:option:`` role, for example
+``:option:`hv.DEBUG_OPTIONS.RELEASE``` would link to
+:option:`hv.DEBUG_OPTIONS.RELEASE`.
+
+The transformed option documentation is
+created in the ``_build/rst/reference/configdoc.txt`` file and included by
+``doc/reference/config-options.rst`` to create the final published
+:ref:`scenario-config-options` document.  You make changes to the option
+descriptions by editing the documentation found in one of the ``.xsd`` files.
+
+
 Documentation Generation
 ************************
 

doc/tutorials/docbuild.rst

@@ -8,6 +8,10 @@ documentation and publishing it to https://projectacrn.github.io.
 You can also use these instructions to generate the ACRN documentation
 on your local system.
 
+.. contents::
+   :local:
+   :depth: 1
+
 Documentation Overview
 **********************
 
@@ -67,14 +71,15 @@ recommended folder setup for documentation contributions and generation:
          misc/
       acrn-kernel/
 
-The parent ``projectacrn folder`` is there because we'll also be creating a
+The parent ``projectacrn folder`` is there because, if you have repo publishing
-publishing area later in these steps.  For API documentation generation, we'll also
+rights, we'll also be creating a publishing area later in these steps.  For API
-need the ``acrn-kernel`` repo contents in a sibling folder to the
+documentation generation, we'll also need the ``acrn-kernel`` repo contents in a
-acrn-hypervisor repo contents.
+sibling folder to the acrn-hypervisor repo contents.
 
-It's best if the ``acrn-hypervisor``
+It's best if the ``acrn-hypervisor`` folder is an ssh clone of your personal
-folder is an ssh clone of your personal fork of the upstream project
+fork of the upstream project repos (though ``https`` clones work too and won't
-repos (though ``https`` clones work too):
+require you to
+`register your public SSH key with GitHub <https://github.com/settings/keys>`_):
 
 #. Use your browser to visit https://github.com/projectacrn and do a
    fork of the **acrn-hypervisor** repo to your personal GitHub account.)
@@ -100,8 +105,11 @@ repos (though ``https`` clones work too):
       cd acrn-hypervisor
       git remote add upstream git@github.com:projectacrn/acrn-hypervisor.git
 
+   After that, you'll have ``origin`` pointing to your cloned personal repo and
+   ``upstream`` pointing to the project repo.
+
 #. For API documentation generation we'll also need the ``acrn-kernel`` repo available
-   locally:
+   locally into the ``acrn-hypervisor`` folder:
 
    .. code-block:: bash
 
@@ -151,7 +159,7 @@ Then use ``pip3`` to install the remaining Python-based tools:
    cd ~/projectacrn/acrn-hypervisor/doc
    pip3 install --user -r scripts/requirements.txt
 
-Add ``$HOME/.local/bin`` to the front of your ``PATH`` so the system will
+Use this command to add ``$HOME/.local/bin`` to the front of your ``PATH`` so the system will
 find expected versions of these Python utilities such as ``sphinx-build`` and
 ``breathe``:
 
@@ -159,7 +167,7 @@ find expected versions of these Python utilities such as ``sphinx-build`` and
 
    printf "\nexport PATH=\$HOME/.local/bin:\$PATH" >> ~/.bashrc
 
-.. note::
+.. important::
 
    You will need to open a new terminal for this change to take effect.
    Adding this to your ``~/.bashrc`` file ensures it is set by default.
@@ -197,7 +205,7 @@ another ``make html`` and the output layout and style is changed. The
 sphinx build system creates document cache information that attempts to
 expedite documentation rebuilds, but occasionally can cause an unexpected error or
 warning to be generated.  Doing a ``make clean`` to create a clean
-generation environment and a ``make html`` again generally cleans this up.
+generation environment and a ``make html`` again generally fixes these issues.
 
 The ``read-the-docs`` theme is installed as part of the
 ``requirements.txt`` list above.  Tweaks to the standard