Commit Graph

52 Commits

Author SHA1 Message Date
David B. Kinder 478a550ba6 doc: tweak CSS to outdent numbered step icons
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2022-08-27 17:21:35 -07:00
David B. Kinder f71c7a8032 doc: use DX-friendly names in configuration option documentation
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>
2022-04-28 07:56:35 -07:00
David B. Kinder b0b5229327 doc: fix table CSS font size changing with lists
The read-the-docs theme uses a reduced font size within tables.  The CSS
used though is overly restrictive and doesn't properly handle tables
containing lists or other constructs where the paragraph tags don't have
the <td> tag within the table as the immediate parent.  Add an
overriding style in our custom CSS to fix this so the font size on lists
within a table are the same as normal paragraphs within a table.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2022-04-18 18:36:39 -07:00
Geoffroy Van Cutsem 8b16be9185 Remove "All rights reserved" string headers
Many of the license and Intel copyright headers include the "All rights
reserved" string. It is not relevant in the context of the BSD-3-Clause
license that the code is released under. This patch removes those strings
throughout the code (hypervisor, devicemodel and misc).

Tracked-On: #7254
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
2022-04-06 13:21:02 +08:00
David B. Kinder ae0820760a doc: add CSS color styles
Add some color styles we can use (via .. rst-class:: style directive) to
add color to rst tables.  Also introduce a centered class instead of
using the deprecated .. centered:: directive.  Update documentation
guidelines to describe these new styles (background colors).

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2021-12-14 16:58:16 -08: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 0bcb66e94e doc: tweak CSS for Sphinx/Breathe API documents
Words in the function prototypes looked run together making it hard to
read, so tweak the CSS to add a bit of padding.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2021-11-02 17:28:02 -07:00
David B. Kinder e2e33f76b9 doc: update to sphinx_rtd_theme 1.0
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>
2021-10-19 13:04:01 -07:00
David B. Kinder 530baaafc6 doc: more GSG DX tweaks
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2021-08-23 14:04:55 -07:00
David B. Kinder 1e175b3146 doc: update v2.4 release notes
Update draft release notes with more information about documentation.
Remove code-block extra indenting.
Add label to roscube gsg so we can link to it (in the releaes notes).
Fix style for :option: references to make them look more links links.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2021-03-29 19:32:07 -07:00
Jian Jun Chen f2d169e9e6 doc: add script to build acrn ovmf with GOP driver
Add a script to build acrn ovmf with GOP driver. The build is
using a ubuntu 16.04 based docker image.

Signed-off-by: Jian Jun Chen <jian.jun.chen@intel.com>
2021-02-08 10:46:21 -08:00
David B. Kinder 2fd1a79ef0 doc: keep doxygen group descriptions in doc output
Propagated fix from other doxygen/breathe project to keep the
description found in the doxygen comments for the group being displayed
(in case there actually is a nice description given).

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-07-10 13:50:58 -07:00
David B. Kinder 9ff0d30ad6 doc: fix style for lists in note
Fix CSS style for lists inside a note.  Previously the first list item
would overlap in the note heading box.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-06-18 13:33:01 -07:00
David B. Kinder 86eb68a1e7 doc: open external links in new tab
As a UX improvement, use a separate tab when opening links to external
sites (use the same tab for internal links).  Also, use rel=noopener
attribute to improve security when linking to external sites.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-06-17 15:58:49 -07:00
David B. Kinder 13e8e3c7f2 doc: adjust search results to bias certain docs
Improve usability of search results to promote tutorials and developer
guides, and demote API and KConfig material, with release notes at the
end.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-06-15 12:30:36 -07:00
David B. Kinder 4db42c1c7f doc: fix rst-columns display
Using ``.. rst-class:: rst-columns`` wasn't processed correctly because
of an error in the acrn-custom.css file.  Fix that, update the
documentation guidelines, and make use of the multi-column display in
documents where the toctree created a long list.  Now it will
appear in columns.

Also tweaked the toctree listing to use bold for the first-level items
(making a multi-column display look better, particularly when it has
subsections).

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-05-21 15:08:15 -07:00
Junming Liu 3ccbb20087 doc:add tutorial about enabling GVT-d
Previous tutorial "Enable GPU Passthrough on the Skylake NUC"
is out of date, so delete it here.

v2 -> v1:
add attached file

Signed-off-by: Junming Liu <junming.liu@intel.com>
2020-05-20 11:58:19 -04:00
David B. Kinder e91eee2ab6 doc: update custom CSS with additional styles
Add styles for multi-column display, and for auto-numbered instruction
steps used in some other projects.

Also updating the used page width to 1100px following experience
improvements noted on other sites.  Pages are hard to read when
displayed full-screen on really wide monitors.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-04-08 16:59:22 -07:00
David B. Kinder 3a326056fd doc: some additional google analytics code
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-04-07 17:18:31 -07:00
Deb Taylor 47b1a936ad Doc: Remove Construction Progress label from site
Signed-off-by: Deb Taylor <deb.taylor@intel.com>
2020-03-25 13:39:51 -04:00
David B. Kinder 3743edf9c1 doc: add site under construction page header
While the site is being reorganized, let's put a header on each page
letting people know.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-03-11 09:06:59 -07:00
David B. Kinder 4d4c4e7b68 doc: remove modernizr.min.js
modernizr.min.js is no longer used by Sphinx's rtd theme and is causing
some browsers to have a noticable flash when pages are loaded. While we
can't easily remove it from the RTD theme, we can replace the script
with an empty file instead.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-08-16 15:36:46 -07:00
David B. Kinder abd8b710a4 doc: improve CSS for home page grid
Update the ACRN logo size to remove specifics in the CSS.  (Grid images
should be ~100px high for the grid.)

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-08-02 09:53:34 -07:00
David B. Kinder a1cc860d5d doc: fix image proportions on home page for ie
The ACRN icon on the new graphical home page looked fine with firefox,
edge, and chrome browsers, but not on IE.  This PR fixes that

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-08-02 07:56:42 -07:00
David B. Kinder 0d07dad5cb doc: additional doc navigation restructuring
Adjust doc navigation organization based on additional feedback.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-08-01 21:30:22 -07:00
David B. Kinder 2ccd652607 doc: simplify navigation with restored doc org
A few more tweaks to the site navigation since we moved the content back
to its original folder structure.

Remove the temporary "doc reorg in progress" banner.

Add reference to hardware in the "try" section.

Add link to the documentation home page in left nav pane.

Add additional redirects to handle external links to moved content.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-08-01 16:22:50 -07:00
David B. Kinder e2d3653976 doc: continue doc restructuring
Changing the folder structure will cause too many broken links for
external references (from other sites). So, let's put the content back
where it was before the reorg, and instead use the new persona-based
navigation to point to documents in the original locations.

Also, introduce redirects for some documents that no longer exits.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-08-01 14:07:22 -07:00
David B. Kinder 11d4f4159f doc: Reorganize documentation site content
Take the existing ACRN technical documentation and reorganize its
presentation to be persona and use-case based, in preparation for adding
new scenario/use-case based architecture introduction and getting
started documents.

Introduce a more graphical home page and theme color tweaks.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-07-31 18:29:22 -07:00
David B. Kinder fe470cfe23 doc: make doc version selector more obvious
Move the doc version selector menu higher on the left nav to make it
more visible (from its prior bottom of the nav menu)

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-04-04 14:47:23 -07:00
David B. Kinder 7f9779b736 doc: add skylake NUC w/GPU passthrough doc
Document a community reference release for the Skylake NUC with GPU
passthrough as a one-time snapshot release, not supported or
maintained.  Includes a tar patch file.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-01-09 09:45:06 -08:00
David B. Kinder 5ebaaaf973 doc: add CSS for non-compliant code examples
Coding guidelines have examples for compliant and non-compliant code,
but they look the same when rendered as HTML.  Add a CSS style for
non-compliant-code examples with a red-tinted background.

Usage is:
```
.. rst-class:: non-compliant-code

   .. code-block:: c

      a=b=c=0;
```
or, for example:

```
.. rst-class:: non-compliant-code

   Here's an example of non-compliant code::

      a=b=c=0;
```

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-12-26 11:09:46 -08:00
David B. Kinder 90d7bddd2f doc: vertical align table content to top
Default vertical alignment of "middle" doesn't look good on large
tables, so override to be "top" of the cell.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-12-12 15:28:59 -08:00
David B. Kinder e24039a7ef doc: tweak CSS for doxygen API usability
Change background colors of API elements to improve readability and
match configuration documentation look.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-12-05 11:44:27 -08:00
David B. Kinder d08256dfa9 doc: code-block text not readable
The .. code-block:: console directive (used for white text on a black
background) didn't handle some CSS cases properly resulting in
unreadable grey text on a black background.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-09-24 15:31:37 -07:00
David B. Kinder 56904bc235 doc: CSS tweak for table caption location
Default behavior is for figure captions below the figure, but table
captions above the table.  Tweak the CSS for tables to put the caption
below instead.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-08-01 11:18:49 -07:00
David B. Kinder ce7257e12e doc: tweak logo href to projectacrn.org
Have the logo link to the project site rather than the doc site

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-07-31 12:04:36 -07:00
David B. Kinder d4d8a128cf doc: tweak formatting for :kbd: role
update custom css to make kbd tag more interesting

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-07-30 16:13:03 -07:00
David B. Kinder 6c54cba985 doc: cleanup css, search, version choices
Update CSS customization to improve read-the-docs theme for our use.
Improved search results (removing most reST markup), improve display of
doc version choices.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-07-26 14:00:49 -07:00
David B. Kinder e04255822a doc: update GSG for v0.1, add console code-block
Console screen shots are hard to maintain, so use the
.. code-block:: console directive to show terminal console-like display
(black background with white text)

Change existing .. code-block:: console uses to .. code-block: none

Replace screen-shot images in apl-nuc getting started guide with
text-based console display.

Update apl-nuc GSG content with v0.1 changes

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-07-16 13:51:28 -07:00
David B. Kinder 6d63cb3cba doc: fix error in custom CSS file
Typo caused some styles to be missed

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-23 09:05:22 -07: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 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 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 b170e295a7 doc: general edit for typos
Fix typos and misspellings, and tweak CSS for spacing before lists.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-15 17:19:35 +08:00
David B. Kinder af66e95112 doc: remove "under construction" tagline
we're getting close...

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-15 17:19:35 +08:00
David B. Kinder da54bde3a7 doc: add Getting Started Guide
Initial version of Getting Started Guide doc (and images).
Need to replace images with better ones.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-15 17:19:35 +08:00
David B. Kinder 48df39c8fd doc: add 0.1 release notes
Initial version of 0.1 release notes, plus a CSS tweak for tables

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-15 17:19:35 +08:00
David B. Kinder b9b20fa6a8 doc: add developer primer
Developer Primer and images, and a tweak to figure formatting
also renamed from Hypervisor Primer to just Developer Primer since the
doc talks about Device Model too.

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