github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-08-07 19:24:34 +00:00
Code Issues Projects Releases Wiki Activity

doc: update doc building howto

Browse Source 
Post-merge, the doc building instructions need an update to reflect the
new diretory structure.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2018-05-11 13:16:03 -07:00
parent 881d54c6fd
commit 4493b425c7
2 changed files with 33 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/howtos/process/acrn-doc-fork.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 54 KiB

After

Width:  |  Height:  |  Size: 62 KiB

66
doc/howtos/process/docbuild.rst
View File

@ -28,8 +28,8 @@ The project's documentation contains the following items:
are found in this acrn-documentation repo. are found in this acrn-documentation repo.
* Doxygen-generated material used to create all API-specific documents * Doxygen-generated material used to create all API-specific documents
found at http://projectacrn.github.io/api/. Clones of the found at http://projectacrn.github.io/api/. Source files from the
acrn-hypervisor and acrn-devicemodel repos are also used to access 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. header files for the the public APIs, but more about that later.
The reStructuredText files are processed by the Sphinx documentation system, The reStructuredText files are processed by the Sphinx documentation system,
@ -54,50 +54,47 @@ You'll need git installed to get the working folders set up:
sudo dnf install git sudo dnf install git
Because we need up-to-date header files to generate API docs, doc We use the source header files to generate API docs and we use github.io
generation assumes the three repos are cloned as sibling folders. for publishing the generated documentation.
Here's the recommended folder setup for documentation contributions and Here's the recommended folder setup for documentation contributions and
generation: generation:
.. code-block: none .. code-block: none
projectacrn/ projectacrn/
acrn-documentation/
acrn-hypervisor/ acrn-hypervisor/
acrn-devicemodel/ devicemodel/
doc/
hypervisor/
It's best if these folders are ssh clones of your personal forks of the The parent projectacrn folder is there because we'll also be creating a
upstream project ACRN repos (though https clones work too): 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):
#. Use your browser to visit https://github.com/projectacrn. One at a #. Use your browser to visit https://github.com/projectacrn and do a
time, visit the **acrn-documentation**, **acrn-hypervisor**, and fork of the **acrn-hypervisor** repo to your personal GitHub account.)
**acrn-devicemodel** repos and do a fork to your personal GitHub account.
.. image:: acrn-doc-fork.png .. image:: acrn-doc-fork.png
:align: center :align: center
#. At a command prompt, create the working folder and clone the three #. At a command prompt, create the working folder and clone the acrn-hypervisor
repositories to your local computer: 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:
.. code-block:: bash .. code-block:: bash
cd ~ cd ~
mkdir projectacrn && cd projectacrn mkdir projectacrn && cd projectacrn
git clone git@github.com:<github-username>/acrn-documentation.git git clone git@github.com:<github-username>/projectacrn/acrn-hypervisor.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: #. For the cloned local repos, tell git about the upstream repo:
.. code-block:: bash .. code-block:: bash
cd acrn-documentation cd acrn-hypervisor
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 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 #. 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: and email address for the signed-off-by line in your commit messages:
@ -136,10 +133,10 @@ Depending on your Linux version, install the needed tools:
And for either Linux environment, install the remaining python-based And for either Linux environment, install the remaining python-based
tools: tools:
.. code-block:: bash .. code-block:: bash
cd ~/projectacrn/acrn-documentation cd ~/projectacrn/acrn-hypervisor/doc
pip3 install --user -r scripts/requirements.txt pip3 install --user -r scripts/requirements.txt
And with that you're ready to generate the documentation. And with that you're ready to generate the documentation.
@ -148,36 +145,38 @@ Documentation presentation theme
Sphinx supports easy customization of the generated documentation Sphinx supports easy customization of the generated documentation
appearance through the use of themes. Replace the theme files and do appearance through the use of themes. Replace the theme files and do
another ``make htmldocs`` and the output layout and style is changed. another ``make html`` and the output layout and style is changed.
The ``read-the-docs`` theme is installed as part of the The ``read-the-docs`` theme is installed as part of the
``requirements.txt`` list above. ``requirements.txt`` list above.
Running the documentation processors Running the documentation processors
************************************ ************************************
The acrn-documentation directory has all the .rst source files, extra tools, and Makefile for 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. generating a local copy of the ACRN technical documentation.
.. code-block:: bash .. code-block:: bash
cd ~/projectacrn/acrn-documentation cd ~/projectacrn/acrn-hypervisor/doc
make html make html
Depending on your development system, it will take about 15 seconds to 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 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`` output with your browser started at ``~/projectacrn/acrn-hypervisor/doc/_build/html/index.html``
Publishing content Publishing content
****************** ******************
If you have push rights to the projectacrn repo called 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. found at https://projectacrn.github.io.
You'll need to do a one-time clone the upstream repo: 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):
.. code-block:: bash .. code-block:: bash
cd ~/projectacrn
git clone git@github.com:projectacrn/projectacrn.github.io.git git clone git@github.com:projectacrn/projectacrn.github.io.git
Then, after you've verified the generated HTML from ``make html`` looks Then, after you've verified the generated HTML from ``make html`` looks
@ -187,7 +186,8 @@ good, you can push directly to the publishing site with:
make publish make publish
This will delete everything in the publishing repo (in case the new version has 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 deleted files) and push a copy of the newly-generated HTML content
directly to the GitHub pages publishing repo. The public site at directly to the GitHub pages publishing repo. The public site at
https://projectacrn.github.io will be updated (nearly) immediately https://projectacrn.github.io will be updated (nearly) immediately