diff --git a/Makefile b/Makefile index 28576ae69..4859f8608 100644 --- a/Makefile +++ b/Makefile @@ -33,7 +33,7 @@ doxy: pullsource $(Q)(cat acrn.doxyfile) | doxygen - 2>&1 html: doxy - $(Q)$(SPHINXBUILD) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O) > doc.log 2>&1 + -$(Q)$(SPHINXBUILD) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O) > doc.log 2>&1 $(Q)./scripts/filter-doc-log.sh doc.log diff --git a/docbuild.rst b/docbuild.rst new file mode 100644 index 000000000..0ec23aebc --- /dev/null +++ b/docbuild.rst @@ -0,0 +1,219 @@ +.. _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/. Clones of the + acrn-hypervisor and acrn-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 + +Because we need up-to-date header files to generate API docs, doc +generation assumes the three repos are cloned as sibling folders. +Here's the recommended folder setup for documentation contributions and +generation: + +.. code-block: none + + projectacrn/ + acrn-documentation/ + acrn-hypervisor/ + acrn-devicemodel/ + +It's best if these folders are ssh clones of your personal forks of the +upstream project ACRN repos (though https clones work too): + +#. Use your browser to visit https://github.com/projectacrn. One at a + time, visit the **acrn-documentation**, **acrn-hypervisor**, and + **acrn-devicemodel** repos and do a fork to your personal GitHub account. + + .. image:: images/acrn-doc-fork.png + :align: center + +#. At a command prompt, create the working folder and clone the three + repositories to your local computer: + + .. code-block:: bash + + cd ~ + mkdir projectacrn && cd projectacrn + git clone git@github.com:/acrn-documentation.git + git clone git@github.com:/acrn-hypervisor.git + git clone git@github.com:/acrn-devicemodel.git + +#. For each of the cloned local repos, tell git about the upstream repos: + + .. code-block:: bash + + cd acrn-documentation + git remote add upstream git@github.com:projectacrn/acrn-documentation.git + cd ../acrn-hypervisor + git remote add upstream git@github.com:projectacrn/acrn-hypervisor.git + cd ../acrn-devicemodel + git remote add upstream git@github.com:projectacrn/acrn-devicemodel.git + cd .. + +#. 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.6.7 +* Breathe version 4.7.3 +* docutils version 0.14 +* sphinx_rtd_theme version 0.2.4 + +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 + +* For Fedora use: + + .. code-block:: bash + + sudo dnf install doxygen python3-pip python3-wheel make + +And for either Linux environment, install the remaining python-based +tools: + + .. code-block:: bash + + cd ~/projectacrn/acrn-documentation + 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 htmldocs`` 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-documentation 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-documentation + 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-documentation/_build/html/index.html`` + +Publishing content +****************** + +If you have push 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 the upstream repo: + +.. code-block:: bash + + 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 (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/ diff --git a/images/acrn-doc-fork.png b/images/acrn-doc-fork.png new file mode 100644 index 000000000..9a06ba180 Binary files /dev/null and b/images/acrn-doc-fork.png differ diff --git a/index.rst b/index.rst index efc794779..7760e34e6 100644 --- a/index.rst +++ b/index.rst @@ -31,6 +31,7 @@ Sections release_notes.rst contribute.rst api/index.rst + docbuild.rst Indices and Tables ****************** diff --git a/scripts/requirements.txt b/scripts/requirements.txt index cde1f185d..5adbdfa6d 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -1,4 +1,4 @@ breathe==4.7.3 -sphinx==1.6.5 +sphinx==1.6.7 docutils==0.14 sphinx_rtd_theme