github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-09-10 05:09:01 +00:00
Code Issues Projects Releases Wiki Activity

doc: use DX-friendly names in configuration option documentation

Browse Source 
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>
This commit is contained in:
David B. Kinder
2022-04-20 14:09:22 -07:00
committed by David Kinder
parent f8f1689a88
commit f71c7a8032
16 changed files with 328 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/developer-guides/doc_guidelines.rst
View File

@@ -751,9 +751,9 @@ During the documentation ``make html`` processing, the documentation annotations
in the ``.xsd`` files are extracted and transformed into reStructuredText using
an XSLT transformation found in ``doc/scripts/configdoc.xsl``. The generated
option documentation is organized and formatted to make it easy to create links
to specific option descriptions using an ``:option:`` role, for example,
``:option:`hv.DEBUG_OPTIONS.BUILD_TYPE``` would link to
:option:`hv.DEBUG_OPTIONS.BUILD_TYPE`.
to specific option descriptions using an ``:term:`` role, for example,
``:term::`Build type``` would link to
:term:`Build type`.
The transformed option documentation is
created in the ``_build/rst/reference/configdoc.txt`` file and included by