We use a post-processor to scan the output log from Sphinx to remove
known errors and warnings before deciding if the Sphinx build was
successful. If an exception happened during the Sphinx build, (see
about the error would appear. Update the Makefile to not stop on errors
for the Sphinx build. The post-processor will stop the make by returning
an error code if it finds unexpected errors in the log.
Tracked-On: #7249
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>
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>
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>
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>
Update missing captions on figures to remove remaining broken references
during latexpdf building. Also, require doing a "make html" before
doing a "make latexpdf" to build all the artifacts needed for running
the latexpdf build. (We might change that later if needed.)
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>
There is a comment in the doc/Makefile that is beinhg spit out
when calling 'make clean'. This is harmless but can be confusing
to users so let's make it silent.
Tracked-On: #5669
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@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>
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>
Add a site-wide custom error page for broken references within the site.
Besides giving a better user experience, it's also easier to track
broken links to the site using google analytics (looking for hits to the
404.html page and noticing the referrer.
Note we only "publish" the custom 404.html when publishing the latest
documents (not for released versions) so we always get the latest
left-navigation menu when a 404 error occurs.
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>
PR #3483 cleaned up the project root folder and moved stuff that was in
/tools into a new /misc folder. There were a few references to
the old /tools folder missed in that update, addressed in this PR.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This patch is to clean-up acrn-hypervisor root directory, targt only 5 folders under acrn-hypervisor:1.hypervisor,2.devicemodel,3.misc,4.doc,5.build
Tracked-On: #3482
Signed-off-by: Terry Zou <terry.zou@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
The doxygen-collected API information about function preconditions has a
uninspired title of "pre". This change tweaks that to be
"preconditions" in the generated HTML output by editing the generated
xml output before it is processed by Sphinx/Breathe.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Sphinx supports making a single (large) html file instead of a
full website with a collection of html pages. This ``make singlehtml``
option provides the basis for creating a Word document (for example)
via a cut-and-paste of a section of the documentation (not easily
possible when the docs are in multiple HTML files.)
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>
Need to make sure the local projectacrn.github.io is in sync with the
master before starting up the publishing process.
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>
Normal publication is to the /latest/ folder. With the tagged 0.1
release, we now have an alternative frozen version of the docs.
Also, tweaked the code for collecting version information from the
VERSION file to create document version number, and Makefile needed to
create the publish directory for a new tagged version.
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>
This patch adds a new target to build the documentation
from the top-level directory. Here is how to use it (from
the top-level source directory):
$ make doc
Or
$ make O=build-test doc
To clean all documentation build artefacts, simply call
$ make clean
Or
$ make O=build-test clean
Calling 'make' with no arguments will *not* build the
documentation by default.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This patch renames $(O) used in the documentation Makefile
(doc/Makefile) into $(OPTS) in order to avoid a namespace
conflict with $(O) used in the top-level Makefile.
This is in preparation to a new target called 'doc' that will
allow to build the documentation directly from the top-level
Makefile. This is required in order *not* to break setting a
specific build directory, e.g. 'make O=build-test'.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@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>
Some assumptioins about the doc build process were removed to make it
easier for contributors to build local version of the docs. Assumption
now is that acrn-hypervisor and acrn-devicemodel content is up to date
rather than pulling from upstream on every build.
make pullsource will do an upstream pull manually
make html generates local docs
Also fixed broken link in the README.md file (moved the tech doc root)
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>
Per Project ACRN governance, documentation is under a Creative Commons
Attribution 4.0 International License (CC BY 4.0). This patch updates
this information, and adds a tagline to documentation mentioning this
license.
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>
Simplify the publishing process to projectacrn.github.io by making
commits directly to the projectacrn/projectacrn.github.io repo (rather
than to a personal repo, doing a PR, and processing the PR). This
eliminates manual processing in an otherwise automated publishing
process: PR reviews aren't needed for this step.
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