Commit Graph

35 Commits

Author SHA1 Message Date
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