Commit Graph

43 Commits

Author SHA1 Message Date
David B. Kinder 487961ace6 doc: fix Makefile to report errors if exception raised
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>
2022-04-02 14:03:46 -07:00
David B. Kinder 81336a8ee4 doc: use Sphinx extension for showing last updated date in footers
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>
2022-03-18 11:05:50 -07:00
David B. Kinder 8fb3ca83a6 doc: update last updated information on page footers
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>
2021-11-03 19:10:56 -07:00
David B. Kinder abb564ba41 doc: add top-level redirect
* 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>
2021-10-28 13:22:14 -07:00
David B. Kinder 09e5df01b1 doc: remove obsolete kconfig references in Makefile
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2021-08-06 09:34:45 -07:00
David B. Kinder 24b555c75d doc: remove doc dependency on kerneldoc and acrn-kernel repo
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>
2021-07-14 18:56:07 -07:00
David B. Kinder 0e317d56bf doc: clean up PDF generation for ACRN docs
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>
2021-04-26 19:50:44 -07:00
David B. Kinder f596b6df13 doc: tweaks for latexpdf build
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>
2021-04-22 11:12:07 -07:00
David B. Kinder c741468b9c doc: remove Kconfig reference documentation
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>
2021-02-03 09:01:40 -08:00
Yang, Yu-chu f1c339df2a doc: integrate config xsl transform into doc build
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>
2021-02-01 09:27:02 +08:00
Geoffroy Van Cutsem d55ab87331 Makefile: make internal comment in doc Makefile silent
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>
2021-01-28 08:46:41 -08:00
David B. Kinder a29ef9178e doc: remove /404.html redirect
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>
2020-04-09 14:21:46 -07:00
David B. Kinder b67d88cab3 doc: fix 404 processing
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>
2020-04-08 14:37:04 -07:00
David B. Kinder dffa75e50f doc: add a custom 404 page
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>
2020-04-08 12:53:37 -07:00
Geoffroy Van Cutsem 1794d994b6 doc: update doc generation tooling to only work within the $BUILDDIR
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>
2019-10-14 17:26:48 -04:00
David B. Kinder 8ee1615e51 doc: fix issues from moving tools to misc/tools
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>
2019-07-29 14:23:04 -07:00
Terry Zou a9c38a5cfb HV:Acrn-hypvervisor Root Directory Clean-up and create misc/ folder for Acrn daemons, services and tools.
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>
2019-07-29 22:58:24 +08:00
David B. Kinder 86d3065de1 doc: tweak doxygen precondition label
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>
2019-06-17 11:19:44 -07:00
David B. Kinder c09046abbf doc: add robots.txt
use a robots.txt file to prevent search engines from indexing old
content.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-04-04 15:51:27 -07:00
David B. Kinder f0ec5b26af doc: add Makefile option for singlehtml
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>
2018-11-12 09:47:12 -08:00
David B. Kinder 8e21d5ee99 doc: update genrest script for latest kconfiglib
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>
2018-10-04 14:25:00 -07:00
David B. Kinder a47f5d4129 doc: fix Makefile to address multiple publishers
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>
2018-09-16 14:30:05 -07:00
David B. Kinder 348422dba6 doc: fix graphviz scanning and processing
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>
2018-08-30 14:05:50 -07:00
David B. Kinder 3abfdbab72 doc: add script for syncing acrn-kernel for API gen
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>
2018-07-24 17:20:43 -07:00
David B. Kinder b4a6b93d5c doc: add v0.1 doc choice
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>
2018-07-12 07:20:36 -07:00
David B. Kinder 287fc4cb7f doc: add hypervisor kconfig option reference
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>
2018-06-15 15:20:43 -07:00
Geoffroy Van Cutsem 2425583c6b Build system: add target to build documentation
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>
2018-06-15 13:32:08 +08:00
Geoffroy Van Cutsem 0dd3f8dbe6 Documentation Makefile: rename $(O) into $(OPTS)
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>
2018-06-15 13:32:08 +08:00
David B. Kinder d57ced490b doc: add doc build infrastructure for tools
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>
2018-05-29 14:23:32 -07:00
David B. Kinder f8861806f0 doc: post-merge changes to docs
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>
2018-05-15 18:03:33 +08:00
Geoffroy Van Cutsem 12fb4b0584 doc: Adjust various scripts accordingly
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-15 18:02:07 +08:00
David B. Kinder 7dd647672c doc: GSG formating fix, RTD theme tweak
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>
2018-05-15 17:25:58 +08:00
David B. Kinder e0a45e8c0f doc: fix doc build processing
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>
2018-05-15 17:25:57 +08:00
David B. Kinder b997e590f2 doc: add support for publishing versioned docs
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>
2018-05-15 17:25:54 +08:00
David B. Kinder d8b1fd2682 doc: add doc building/publishing instructions
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>
2018-05-15 17:19:37 +08:00
David B. Kinder c8d2cdccda doc: update project documentation LICENSE
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>
2018-05-15 17:19:35 +08:00
David B. Kinder 0dc93a5281 doc: filter known issues
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>
2018-05-15 17:19:35 +08:00
David B. Kinder c48f757e6d doc: Update publish process in Makefile
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>
2018-05-15 17:19:35 +08:00
David B. Kinder ba121731b2 doc: add Technical intro doc
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>
2018-05-11 14:44:29 +08:00
David B. Kinder 8d7a449c55 doc: fix source file fetching and cleaning
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-11 14:44:27 +08:00
David B. Kinder 4c941d5e5b improve automation
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-11 14:44:27 +08:00
David B. Kinder dce61618dc doc: organizational and look improvements
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-11 14:44:27 +08:00
David B. Kinder d7938f8ca8 doc: initial doc commit
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-11 14:44:27 +08:00