doc: add doc building/publishing instructions
Add a new document describing how doc building and publishing works and how to setup a doc working directory and build tools to make it so. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
parent
eb31977817
commit
d8b1fd2682
|
@ -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
|
||||
|
||||
|
||||
|
|
|
@ -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:<github-username>/acrn-documentation.git
|
||||
git clone git@github.com:<github-username>/acrn-hypervisor.git
|
||||
git clone git@github.com:<github-username>/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/
|
Binary file not shown.
After Width: | Height: | Size: 54 KiB |
|
@ -31,6 +31,7 @@ Sections
|
|||
release_notes.rst
|
||||
contribute.rst
|
||||
api/index.rst
|
||||
docbuild.rst
|
||||
|
||||
Indices and Tables
|
||||
******************
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
breathe==4.7.3
|
||||
sphinx==1.6.5
|
||||
sphinx==1.6.7
|
||||
docutils==0.14
|
||||
sphinx_rtd_theme
|
||||
|
|
Loading…
Reference in New Issue