Commit Graph

24 Commits

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