github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-21 05:02:24 +00:00
Code Issues Projects Releases Wiki Activity

doc: update doc-build tutorial

Browse Source 
Last year, GitHub announced the deprecation of the unsecured Git
protocol due to security reasons. This change will be made permanent on
March 15, 2022. Update the doc build tutorial to use https: instead of
git: protocol for cloning repos.

And while in here, clarify some of the doc build instructions.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2022-03-09 08:39:08 -08:00 committed by David Kinder
parent 5c5fbd6a5b
commit b72202e976
1 changed files with 27 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
doc/tutorials/docbuild.rst
View File

@ -72,10 +72,9 @@ recommended folder setup for documentation contributions and generation:
The parent ``projectacrn folder`` is there because, if you have repo publishing The parent ``projectacrn folder`` is there because, if you have repo publishing
rights, we'll also be creating a publishing area later in these steps. rights, 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 In the following steps, you'll create a fork of the upstream ``acrn-hypervisor``
fork of the upstream project repos (though ``https`` clones work too and won't repo to your personal GitHub account, clone your personal fork to your local
require you to development computer, and then link that to the upstream repo as well:
`register your public SSH key with GitHub <https://github.com/settings/keys>`_):
#. Use your browser to visit https://github.com/projectacrn and do a #. Use your browser to visit https://github.com/projectacrn and do a
fork of the **acrn-hypervisor** repo to your personal GitHub account.) fork of the **acrn-hypervisor** repo to your personal GitHub account.)
@ -83,23 +82,21 @@ require you to
.. image:: images/acrn-doc-fork.png .. image:: images/acrn-doc-fork.png
:align: center :align: center
#. At a command prompt, create the working folder and clone the acrn-hypervisor #. At a command prompt, create a working folder on your development computer and
repository to your local computer (and if you have publishing rights, the clone your personal acrn-hypervisor repository:
``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 .. code-block:: bash
cd ~ cd ~
mkdir projectacrn && cd projectacrn mkdir projectacrn && cd projectacrn
git clone git@github.com:<github-username>/projectacrn/acrn-hypervisor.git git clone https://github.com/<github-username>/acrn-hypervisor.git
#. For the cloned local repos, tell git about the upstream repo: #. For the cloned local repo, tell git about the upstream repo:
.. code-block:: bash .. code-block:: bash
cd acrn-hypervisor cd acrn-hypervisor
git remote add upstream git@github.com:projectacrn/acrn-hypervisor.git git remote add upstream https://github.com/projectacrn/acrn-hypervisor.git
After that, you'll have ``origin`` pointing to your cloned personal repo and After that, you'll have ``origin`` pointing to your cloned personal repo and
``upstream`` pointing to the project repo. ``upstream`` pointing to the project repo.
@ -115,15 +112,15 @@ require you to
Install the Documentation Tools Install the Documentation Tools
******************************* *******************************
Our documentation processing has been tested to run with Python 3.6.3 Our documentation processing has been tested to run with Python 3.8.10
and these other tools: and these other tools:
* breathe version: 4.23.0 * breathe version: 4.31.0
* sphinx version: 3.2.1 * sphinx version: 3.5.4
* docutils version: 0.16 * docutils version: 0.16
* sphinx-rtd-theme version: 0.5.0 * sphinx-rtd-theme version: 1.0.0
* sphinx-tabs version: 1.3.0 * sphinx-tabs version: 1.3.0
* doxygen version: 1.8.13 * doxygen version: 1.8.17
Depending on your Linux version, install the needed tools. You may get a Depending on your Linux version, install the needed tools. You may get a
different (newer) version of doxygen noted above that may also work. different (newer) version of doxygen noted above that may also work.
@ -135,7 +132,8 @@ For Ubuntu use:
sudo apt install doxygen python3-pip \ sudo apt install doxygen python3-pip \
python3-wheel make graphviz xsltproc python3-wheel make graphviz xsltproc
Then use ``pip3`` to install the remaining Python-based tools: Then use ``pip3`` to install the remaining Python-based tools specified in the
``requirements.txt`` file:
.. code-block:: bash .. code-block:: bash
@ -161,7 +159,8 @@ And with that you're ready to generate the documentation.
We've provided a script you can run to show what versions of the We've provided a script you can run to show what versions of the
documentation building tools are installed and compare with the documentation building tools are installed and compare with the
tool versions shown above.:: tool versions shown above. This tool will also verify you're using tool
versions known to work together::
doc/scripts/show-versions.py doc/scripts/show-versions.py
@ -241,7 +240,7 @@ with the ``-silent`` options, like this (after you've run ``make html``:
make latexpdf LATEXMKOPTS="-silent" make latexpdf LATEXMKOPTS="-silent"
For convenience, we've also created a make target called ``pdf`` that will first For convenience, we've also created a make target called ``pdf`` that will
generate the HTML content and then make the PDF file in one step: generate the HTML content and then make the PDF file in one step:
.. code-block:: bash .. code-block:: bash
@ -266,7 +265,7 @@ directly to the upstream repo rather than to a personal forked copy):
.. code-block:: bash .. code-block:: bash
cd ~/projectacrn cd ~/projectacrn
git clone git@github.com:projectacrn/projectacrn.github.io.git git clone https://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
good, you can push directly to the publishing site with: good, you can push directly to the publishing site with:
@ -300,18 +299,16 @@ specifically:
'docs_title': docs_title, 'docs_title': docs_title,
'is_release': is_release, 'is_release': is_release,
'versions': ( ("latest", "/latest/"), 'versions': ( ("latest", "/latest/"),
("2.3", "/2.3/"), ("2.7", "/2.7/"),
("2.2", "/2.2/"), ("2.6", "/2.6/"),
("2.1", "/2.1/"), ("2.5", "/2.5/"),
("2.0", "/2.0/"), ("2.0", "/2.0/"),
("1.6.1", "/1.6.1/"), ("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 ("1.0", "/1.0/"), # keep 1.0
) )
} }
As new versions of ACRN documentation are added, update this As new versions of ACRN documentation are added, update this
``versions`` selection list 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 folder. Note that there's no direct selection to go to a newer version
@ -320,16 +317,16 @@ from an older one, without going to ``latest`` first.
By default, documentation build and publishing both assume we're generating By default, documentation build and publishing both assume we're generating
documentation for the main branch and publishing to the ``/latest/`` documentation for the main branch and publishing to the ``/latest/``
area on https://projectacrn.github.io. When we're generating the area on https://projectacrn.github.io. When we're generating the
documentation for a tagged version (e.g., 2.3), check out that version documentation for a tagged version (e.g., 2.7), 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 .. code-block:: bash
cd ~/projectacrn/acrn-hypervisor/doc cd ~/projectacrn/acrn-hypervisor/doc
git checkout v2.3 git checkout v2.7
make clean make clean
make DOC_TAG=release RELEASE=2.3 html make DOC_TAG=release RELEASE=2.7 html
make DOC_TAG=release RELEASE=2.3 publish make DOC_TAG=release RELEASE=2.7 publish
.. _filter_expected: .. _filter_expected: