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:

  sudo apt-get install git
  

• For a Fedora development system use

  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:

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

1. Use your browser to visit https://github.com/projectacrn and do a fork of the acrn-hypervisor repo to your personal GitHub account.)

   

2. 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:

   cd ~
   mkdir projectacrn && cd projectacrn
   git clone git@github.com:<github-username>/projectacrn/acrn-hypervisor.git
   

3. For the cloned local repos, tell git about the upstream repo:

   cd acrn-hypervisor
   git remote add upstream git@github.com:projectacrn/acrn-hypervisor.git
   

4. 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:

   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:

  sudo apt-get install doxygen python3-pip \
    python3-wheel make graphviz
  

• For Fedora use:

  sudo dnf install doxygen python3-pip python3-wheel make graphviz
  

And for either Linux environment, install the remaining python-based tools:

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.

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

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:

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.