Update known-issues processing and tweak conf.py and requirements.txt
(for PyPI package versions) to handle a broader version of
doc-generation tools (sphinx, breathe, docutils, etc.). This should
let us move to Ubuntu 22.04 while maintaining doc-build compatibility
with older tool versions available with Ubuntu 20.04 (doxygen in particular).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
changed-docs.sh (and the accompanying awk script) shows docs changed
between a previous release branch and the current master branch, in a format that
can be used for the releae notes (a list of :ref: items).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Modified the copyright year range in code, and corrected "int32_tel"
into "Intel" in two "hypervisor/include/debug/profiling.h" and
"hypervisor/include/debug/profiling_internal.h".
Tracked-On: #7559
Signed-off-by: Ziheng Li <ziheng.li@intel.com>
Add a configuration parameter for the xsltproc processing to decide
whether to include hidden options.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Fix how the config option doc scripts behave when encountering elements
with blank titles (used to remove extraneous headings in the
configurator UI).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The acrn:views processing for showing which tabs an option would display
on wasn't quite right when an element AND a parent both had a views
attribute (specifically when the parent had "basic, advanced" but the
element only had "basic" or "advanced").
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The configurator today shows "Please Input" as the placeholder of input
widgets, which is far from informative.
This patch specifies element or type specific placeholders in the XML
schema by reusing the `acrn:widget-options` annotation mechanism. For
manually-designed widgets such as ivshmem or vUART the placeholders are
added in the corresponding vue directly.
Tracked-On: #6691
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Reduce expression complexity when searching for applicable-vms and views
annotations and increase ancestor search distance.
Don't sort glossary options to more closely mimic order found in the
configurator.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
When an element in the schema does not have an acrn:applicable-vms or
acrn:views (as opposed to having the attribute with an empty value,
acrn:views="") we need to look up the ancestors to see if any of them
have an element with such an attribute defined. If non of the ancestors
have that attribute defined, then the intrepretation is that the element
can be found for all VMs or for both basic and advanced tabs.
Tweak the xslt processing of the schema data to option config doc to
reflect these semantics.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Change the generated config option documentation to use the DX-friendly
names defined for the configurator UI (instead of the XML element name
hierarchy previously used).
Options are grouped by the top-level section (aka complex type) they
belong to and then sorted alphabetically with these groups.
Use badges to indicate where options can be found in the configurator UI
and whether they're applicable to the Hypervisor or Pre/Post/Service VM.
Add a custom css style for the config-option doc that puts the first
paragraph of a glossary item on the same line as the glossary term so
these badges look pretty.
Added a acrn-custom.js patch that copies the alt text for images into a
title property for images within the config-doc document. This provides
tooltip text when hovering over the badges.
Don't display options not visible in the configurator UI (elements with
acrn:views="").
A missing acrn:views or acrn:applicable-vm means we look for an
applicable value from an ancestor element.
Add processing of a second xs:documentation element within an
xs:annotation element. This second documentation element's content will
be appended as a new paragraph to the first xs:documentation content in
the generated documentation. Only the first xs:documentation element is
used by the Configurator for its tooltips.
Update documents that were referring to options by their XML names.
Because we're now using a glossary to provide links to config options,
we can't duplicate option names or glosary names anywhere in the doc
set.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Remove the proof-of-concept shell script that post-processes the
generated HTML to add the git date when the corresponding .rst file as
the last modified date, augmenting the existing published date.
Instead, use a custom last_updated.py Sphinx extension that's integrated
into the Sphinx build itself. Remove the old fix-git-modified-date.sh
script and calls to it.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
We plan to add the following attributes to element definitions in the XML
schema:
- acrn:applicable-vms, which specify if an element applies to a
pre-launched VM, the service VM or a post-launched VM
- acrn:views, which specify if an element shall appear in the basic or
advanced tab in the configurator.
In order to reduce the attributes above to existing XML technologies, we
need to create new complex types that lists all config items that applies
to a pre-launched VM, the service VM or a post-launched VM, or that should
be shown in the basic or advanced view. Such types can then be used to
replace the original, all-in-one type during validation or configurator
rendering.
When unspecified, an element always applies under all possible
circumstances.
To realize this slicing mechanism, this patch adds a generic class
implementing the common part of slicing XML schema types and two
specific-purpose slicers according to the applicable VMs or views
attributes.
v2 -> v3:
* Update configdoc.xsl to recognize types in xs:alternative nodes.
Tracked-On: #6690
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
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>
David B. Kinder