doc: upgrade doc-build tools

Update the documentation for how to build ACRN documents
(tutorial/docbuild.rst) and the scripts/requirements.txt that lists the
tested configuration of python tools being used.

Previous merged commits have already been made to handle doc builds with
the previous (2.3 documented configuration and the new v2.4
configuration.

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

doc/scripts/requirements.txt

@@ -1,6 +1,6 @@
-breathe==4.9.1
+breathe==4.23.0
-sphinx==1.7.7
+sphinx==3.2.1
-docutils==0.14
+docutils==0.16
-sphinx_rtd_theme==0.4.0
+sphinx_rtd_theme==0.5.0
-kconfiglib>=10.2
+kconfiglib==14.1.0
-sphinx-tabs==1.1.13
+sphinx-tabs==1.3.0

doc/tutorials/docbuild.rst

@@ -12,7 +12,7 @@ Documentation overview
 **********************
 
 Project ACRN content is written using the reStructuredText markup
-language (.rst file extension) with Sphinx extensions, and processed
+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
@@ -34,15 +34,15 @@ The project's documentation contains the following items:
   device-model folders, and from sources in the acrn-kernel repo (as
   explained later).
 
-The reStructuredText files are processed by the Sphinx documentation system,
+The reStructuredText files are processed by the Sphinx documentation system
-and make use of the breathe extension for including the doxygen-generated API
+and use 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:
+You'll need ``git`` installed to get the working folders set up:
 
 * For an Ubuntu development system use:
 
@@ -50,15 +50,9 @@ You'll need git installed to get the working folders set up:
 
      sudo apt-get install git
 
-* For a Fedora development system use
+We use the source header files to generate API documentation and we use
-
+``github.io`` for publishing the generated documentation.  Here's the
-  .. code-block:: bash
+recommended folder setup for documentation contributions and generation:
-
-     sudo dnf install git
-
-We use the source header files to generate API documentation and we use github.io
-for publishing the generated documentation.  Here's the recommended
-folder setup for documentation contributions and generation:
 
 .. code-block: none
 
@@ -70,12 +64,12 @@ 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 we'll also be creating a
 publishing area later in these steps.  For API documentation generation, we'll also
-need the acrn-kernel repo contents in a sibling folder to the
+need the ``acrn-kernel`` repo contents in a 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 fork of the upstream project
 repos (though ``https`` clones work too):
 
@@ -87,7 +81,7 @@ repos (though ``https`` clones work too):
 
 #. 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
+   ``projectacrn.github.io`` repo).  If you don't have publishing rights
    you'll still be able to generate the documentation files locally, but not publish them:
 
    .. code-block:: bash
@@ -103,7 +97,7 @@ repos (though ``https`` clones work too):
       cd acrn-hypervisor
       git remote add upstream git@github.com:projectacrn/acrn-hypervisor.git
 
-#. For API documentation generation we'll also need the acrn-kernel repo available
+#. For API documentation generation we'll also need the ``acrn-kernel`` repo available
    locally:
 
    .. code-block:: bash
@@ -112,7 +106,7 @@ repos (though ``https`` clones work too):
       git clone git@github.com:projectacrn/acrn-kernel.git
 
    .. note:: We assume for documentation generation that ``origin`` is pointed to
-      the upstream repo.  If you're a developer and have the acrn-kernel
+      the upstream ``acrn-kernel`` repo.  If you're a developer and have the acrn-kernel
       repo already set up as a sibling folder to the acrn-hypervisor,
       you can skip this clone step.
 
@@ -127,14 +121,16 @@ repos (though ``https`` clones work too):
 Installing the documentation tools
 **********************************
 
-Our documentation processing has been tested to run with:
+Our documentation processing has been tested to run with Python 3.6.3
+and these other tools:
 
-* Python 3.6.3
+* breathe                   version: 4.9.1
-* Doxygen version 1.8.13
+* sphinx                    version: 1.7.7
-* Sphinx version 1.7.7
+* docutils                  version: 0.14
-* Breathe version 4.9.1
+* sphinx-rtd-theme          version: 0.4.0
-* docutils version 0.14
+* kconfiglib                version: 10.9.1
-* sphinx_rtd_theme version 0.4.0
+* sphinx-tabs               version: 1.1.13
+* doxygen                   version: 1.8.13
 
 Depending on your Linux version, install the needed tools:
 
@@ -145,14 +141,7 @@ Depending on your Linux version, install the needed tools:
      sudo apt-get install doxygen python3-pip \
        python3-wheel make graphviz
 
-* For Fedora use:
+Then use ``pip3`` to install the remaining Python-based tools:
-
-  .. code-block:: bash
-
-     sudo dnf install doxygen python3-pip python3-wheel make graphviz
-
-And for any of these Linux environments, install the remaining Python-based
-tools:
 
 .. code-block:: bash
 
@@ -169,7 +158,7 @@ find expected versions of Python utilities such as ``sphinx-build`` and
 
 .. note::
 
-   You will need to open a new terminal for this change to be effective.
+   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.
 
 And with that you're ready to generate the documentation.
@@ -177,7 +166,7 @@ And with that you're ready to generate the documentation.
 .. note::
 
    We've provided a script you can run to show what versions of the
-   documentation building tools you have installed ::
+   documentation building tools are installed.::
 
       doc/scripts/show-versions.py
 
@@ -189,8 +178,8 @@ appearance through the use of themes.  Replace the theme files and do
 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 doc
+warning to be generated.  Doing a ``make clean`` to create a clean
-generation and a ``make html`` again generally cleans this up.
+generation environent and a ``make html`` again generally cleans this up.
 
 The ``read-the-docs`` theme is installed as part of the
 ``requirements.txt`` list above.  Tweaks to the standard
@@ -206,7 +195,7 @@ tools, and ``Makefile`` for generating a local copy of the ACRN technical
 documentation.  For generating all the API documentation, there is a
 dependency on having the ``acrn-kernel`` repo's contents available too
 (as described previously).  You'll get a sphinx warning if that repo is
-not set up as described, but you can be ignore that warning if you're
+not set up as described, but you can ignore that warning if you're
 not planning to publish.
 
 .. code-block:: bash
@@ -214,15 +203,16 @@ not planning to publish.
    cd ~/projectacrn/acrn-hypervisor/doc
    make html
 
-Depending on your development system, it will take about 15 seconds to
+Depending on your development system, it will take less than two minutes 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``.  You can
+``~/projectacrn/acrn-hypervisor/doc/_build/html/index.html``. You can
-also ``cd`` to the ``doc/_build/html`` folder and run a local web server
+also ``cd`` to the ``_build/html`` folder and run a local web server
 with the command:
 
 .. code-block:: bash
 
+   cd _build/html
    python3 -m http.server
 
 and use your web browser to open the URL:  ``http://localhost:8000``.
@@ -231,7 +221,7 @@ Publishing content
 ******************
 
 If you have merge rights to the projectacrn repo called
-projectacrn.github.io, you can update the public project documentation
+``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
@@ -253,45 +243,55 @@ 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
+typically within a few minutes, so it's best to verify the locally
-before publishing.
+generated HTML before publishing.
 
 Document Versioning
 *******************
 
 The https://projectacrn.github.io site has a document version selector
-at the bottom of the left nav panel.  The contents of this version
+at the top of the left nav panel.  The contents of this version
 selector are defined in the ``conf.py`` sphinx configuration file,
 specifically:
 
 .. code-block:: python
+   :emphasize-lines: 5-6
 
    html_context = {
       'current_version': current_version,
+      'docs_title': docs_title,
+      'is_release': is_release,
       'versions': ( ("latest", "/latest/"),
-                    ("0.2", "/0.2/"),
+                    ("2.3", "/2.3/"),
-                    ("0.1", "/0.1/"),
+                    ("2.2", "/2.2/"),
+                    ("2.1", "/2.1/"),
+                    ("2.0", "/2.0/"),
+                    ("1.6.1", "/1.6.1/"),
+                    ("1.6", "/1.6/"),
+                    ("1.5", "/1.5/"),
+                    ("1.4", "/1.4/"),
+                    ("1.0", "/1.0/"),   # keep 1.0
                   )
        }
 
-As new versions of documentation are added, this ``versions`` selection
+As new versions of ACRN documentation are added, update this
-list should be updated to include the version number and publishing
+``versions`` selection list to include the version number and publishing
 folder.  Note that there's no direct selection to go to a newer version
 from an older one, without going to ``latest`` first.
 
-By default, documentation build and publishing assumes we're generating
+By default, documentation build and publishing both assume we're generating
 documentation for the main branch and publishing to the ``/latest/``
 area on https://projectacrn.github.io. When we're generating the
-documentation for a tagged version (e.g., 0.2), check out that version
+documentation for a tagged version (e.g., 2.3), check out that version
-of the repo, and add some extra flags to the make commands:
+of the repo, and add some extra flags to the ``make`` commands:
 
 .. code-block:: bash
 
    cd ~/projectacrn/acrn-hypervisor/doc
-   git checkout v0.2
+   git checkout v2.3
    make clean
-   make DOC_TAG=release RELEASE=0.2 html
+   make DOC_TAG=release RELEASE=2.3 html
-   make DOC_TAG=release RELEASE=0.2 publish
+   make DOC_TAG=release RELEASE=2.3 publish
 
 Filtering expected warnings
 ***************************