The "Last Updated" footer shows the date the page was published, not
when the content was last updated. This has caused readers some
confusion. Update the footer with the date of the git commit that last
updated the document, and clarify with both the last modified and
published dates in the footer, something like this:
Last modified: Aug 19, 2021. Published: Nov 03, 2021.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
* Add a script for creating top-level redirects on the
projectacrn.github.io site.
* Use it to generate the top-level index.html redirect to
latest/index.html in the Makefile (for make publsh).
* Generate a new redirect for hardware.html to catch inbound links.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The sphinx_rtd_theme 1.0 includes simplified configuration for Google
analytics, along with general fixes and improvements.
Anyone publishing project documentation to projectacrn.github.io must be
using this updated sphinx_rtd_theme for Google Analytics data to be
properly collected.
* Switch to use this new theme version, and clean up the previous method
of collecting analytics data.
* Update requirements.txt to use this new theme version. Update the
show-versions.py script (used to report on installed doc building tools)
to also report if there's a mismatch on which version is expected (in
requirements.txt) and what's currently installed.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
We no longer need to generate API documentation for the upstreamed
gvt-g kernel additions so we can remove the doc generation dependency on
the acrn-kernel repo (and all use of the kerneldoc extension). We also
remove GVT-g API documentation and porting guide that are obsolete with
ACRN v2.6 and referenced this API documentation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Seperate options with simple types with a heading so they don't get
hidden under the previous options that are part of a complex type.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
PRs #5945 and #5949 introduced fixes to the doc building process to
support PDF generation of the documentation set. This PR refines the
doc build process, cleaning up the Makefile, adding display of tool
version information, and updates the doc building documentation to
include additional dependencies needed for building the PDF and
instructions for how to build the PDF. The latexpdf make target is
provided to just run the latex and PDF producing process that depends on
the HTML artifacts from a make html run. A new make pdf target is
provided that combines the two steps into one.
A new know-issues pattern file is added that verifies the expected
output from the latexpdf process is returned, as it can't be completely
eliminated without losing potential error messages that need to be
resolved.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Some terms in the config option docs (Integer, Boolean) are being
flagged by one of our spell checking tools. Let's make it happy.
Tracked-On: #5692
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Start cleaning up formatting and content layout issues in the
xsd-derived configuration option documentation. Includes adding
documentation for unnamed embedded simple types within an element (and
updates to the XSLT transformation to display these), cleanup of element
and type documentation, typos and description clarity.
Improved xsdl translation to automatically include default values and if
an option is optional (instead of manually documenting this in the
description text).
Tracked-On: #5692
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
With the new ACRN configuration architecture, we no longer use Kconfig
files. Remove the Kconfig option documentation scripting (genrest.py)
Python dependencies, and Makefile commands, and change references in the
documentation from the Kconfig option (such as
:option:`CONFIG_MEM_LOGLEVEL`) to the new schema definition-based option
documentation (:option:`hv.DEBUG_OPTION.MEM_LOGLEVEL`).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Documentation for the scenario XML configuration options is pulled from the
schema definition files (xsd) maintained in the misc/config_tools/schema
folder. Update the doc build process to generate and incorporate the
option documentation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the documentation for how to build ACRN documents
(tutorial/docbuild.rst) and the scripts/requirements.txt that lists the
tested configuration of python tools being used.
Previous merged commits have already been made to handle doc builds with
the previous (2.3 documented configuration and the new v2.4
configuration.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Specify the version of 'sphinx-tabs' to be installed in order
to be able to build the documentation. Without this, the latest
is installed but is incompatible with 'sphinx==1.7.7' as specified
in our doc/scripts/requirements' file.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
The sphinx-tabs extension let's us create a document that can
dynamically display alternate material based on clicking a tab, as used
in the Zephyr getting started guide:
https://docs.zephyrproject.org/latest/getting_started/index.html
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Using a root-level /404.html as a redirect to the /latest/404.html
causes the URL shown in the browser to change so you can't see what the
error-causing URL was. Instead of a redirect, copy the /latest/404.html
generated by Sphinx to /404.html and edited with a <base> tag that
specifies a base URL for all relative URLs on a page.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Developers using google search can accidentally find older versions of
documents and lead to confusion. While we do maintain previous release
documentation on the site, we should have a preference for the latest
documentation when using external search engines. (Note the on-site
search always returns version-specific results.)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Some additional tweaks to the publish script, image, and root-level
redirect to fix a redirect recursion problem.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
PR #3665 moved all the doc build artifacts into the _build folder and
updated scripts and Makefile to account for this, except missed a fix in
the script that checks for known issues. This patch fixes that but shows
we've got a bunch of issues that have not been being reported so we'll
need to fix those problems to resolve failing doc builds.
Also fixed process of the VERSION file in conf.py since the path to that
file was changed by PR #3665 as well and was raising an exeception that
was being masked.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Modify the documentation Makefile (doc/Makefile) and scripts to only modify and
create content inside the $BUILDDIR folder.
The folders that were created inside 'doc/' previously are now all created
inside '$BUILDDIR/rst'. The '.gitignore' file has also been updated accordingly.
Tracked-On: #3686
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This tutorial will describe steps to sign binaries of
a Clear Linux image that allows user to launch VM
throught the secure boot enabled OVMF.
Signed-off-by: lirui34 <ruix.li@intel.com>
Update batch script documentation and add reference to source of
material. Also some grammar cleanup in a few places.
Include an updated install_by_vga_gsg.tar.gz with an updated script with
copyright/licensing added.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Versions of kconfiglib lower than 10.2 cannot build the documentation
correctly. The minimum version required is >=10.2. This patch updates
the 'requirements.txt' accordingly.
Tracked-On: #2429
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Update the 'kernel-doc' script to the latest version available from
https://github.com/projectacrn/acrn-kernel.
This solves the following error when generating the ACRN documentation:
"Unescaped left brace in regex is deprecated here (and will be fatal in Perl
5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE .*})/ at
scripts/kernel-doc line 2176."
Tracked-On: #1926
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
When the doc log is scanned for potential "new" errors, if any are found
it wasn't returning a non-zero error code.
Tracked-on: #1514
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The genrest.py script (used to generate config documentation from the
Kconfig files) broke when upgrading to the latest kconfiglib (10.9.1).
Copied the latest genrest.py script from the Zephyr project (where this
script and processing was developed) and things work again.
Update Makefile's call to genrest.py (toplevel Kconfig path is now found
relative to the srctree.
Update requirements.txt to match the kconfiglib version family
verified to work.
fixes: #1387
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Documentation scripts: enhance 'show-versions.py'
Modify the doc/scripts/show-versions.py script by making it
gather the list of Python modules to check the version for from
the "requirements.txt" file. It should help keep this in sync
if/when our requirements evolve.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
The genrest.py script (used to generate config documentation from the
Kconfig files) broke when upgrading to the latest kconfiglib (10.9.1).
Copied the latest genrest.py script from the Zephyr project (where this
script and processing was developed) and things work again.
Also update requirements.txt to match the kconfiglib version verified to
work.
tracked-on: #1387
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Added a python script that displays versions of doc building tools
(e.g., doxygen, breathe, sphinx) to help verify doc building environment
is properly set up (can help doc building problem diagnostic, as shown
in issue #1333
Update doc build documentation to reference this script.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The doc build process copies files using script/extract-content.py from
outside of the doc/ folder (specifically content in the tools/ folders).
The script was not copying graphviz directive files. This has been
fixed and the embedded graphviz directives are not (properly) stored in
separate image/*.dot files.
Note the extract-content.py file is derived from the Zephyr project.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
API doc generation includes kernel components provided by ACRN that live
in the acrn-kernel repo (not the acrn-hypervisor repo). We need to
include fetching the latest acrn-kernel sources when we do doc
generation, and update the documentation to mention we now need the
acrn-kernel repo as a sibling folder for the acrn-hypervisor repo
contents.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Some ACRN kernel components are using the API documentation methods of
the Linux kernel. While they use Sphinx for generating their
documentation, they don't use doxygen to collect the API information as
we do for the rest of the project. Instead, they use their own tools
called "kerneldoc". This PR incorporates those tools into our
documentation build process.
There is a prescribed directory structure for this to work: that the
acrn-hypervisor and acrn-kernel repos are cloned to sibling folders,
e.g.:
projectacrn
acrn-hypervisor
acrn-kernel
so that documentation references from acrn_hypervisor/doc can access the
source code in ../../acrn-kernel to do the kerneldoc processing. A full
display of the kerneldoc API material for a source file in the
acrn-kernel tree can be done using a sphinx extension directive:
.. kernel-doc:: /tools/virtio/linux/scatterlist.h
where the assumed root of these file references is ../../acrn-kernel.
The format for kerneldoc comments is documented in
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html and
references to kerneldoc API material in .rst files is documented in
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#including-kernel-doc-comments
Without options, the kernel-doc directive includes all documentation
comments from the source file. With options, you can display subsets of
these comments.
The intention is to limit use of kerneldoc comments to the acrn-kernel
repo and not use them elsewhere within the ACRN project (where doxygen
comments are expected.)
While I'd prefer NOT to include the kerneldoc perl script here (it is
already in the acrn-kernel/sphinx folder), I don't want to create a
dependency on the acrn-kernel folder existing for documentation
generation, but this might be unavoidable once we have part of the API
material coming from there. We can update this in a later PR.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Modify the Zephyr project script for creating documentation from Kconfig
files to generate the hypervisor option configuration docs. While Zephyr
uses a modified version of kconfiglib, we can use the standard
kconfiglib from Pypi (added to the requirements.txt file).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The latest versions of Sphinx and Breathe work well together so we're
updating the requirements.txt installation information (and
documentation) to use the latest versions of these tools.
Fixes: #395
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The tools documentation is maintained within the tools folder and
outside of the doc folder. We need to temporarily pull that content
within the doc folder for generating the documentation set. (We're using
a script developed for the Zephyr project for just this purpose.)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Documentation updates were needed to account for changes caused by the
recent merging of the three acrn-hypervisor, acrn-devicemodel, and
acrn-documentation repos.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Fix some formatting problems with a recent GSG update. Tweak the
custom CSS to adjust code block (and code literal) colors. Update
Makefile to document doc build options for pulling source from the other
repos and for publishing targets.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
add navigation to (manually) maintained list (in conf.py) of versioned
docs, and update generating and publishing processes to be
version-aware.
Adds a file to redirect root references to /latest folder now (since we
can't update the server redirects). Might break some links to pages
within the site from external sites.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
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>
make the doc build process quiet and add filtering of known (Sphinx)
issues. Scripting comes from the open source Zephyr project.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Doc version tracking with acrn-hypervisor version now to be
MAJOR_VERSION . MINOR_VERSION . RC_VERSION
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add the "Introduction of Project Acorn" doc.
Also adds improvements to the doc generation processes, content styles,
removed doxygen-generated API material.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
David B. Kinder