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

doc: update doc guidlines for ACRN config options

Browse Source 
Explain how ACRN configuration options are documented and generated

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

Tracked-On: #5911
This commit is contained in:
David B. Kinder
2021-06-10 14:45:12 -07:00
committed by David Kinder
parent 5ec5d9f578
commit 4ea0d49a74
2 changed files with 58 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -653,6 +653,45 @@ This is the second instruction step.
only one set of numbered steps is intended per document and the steps
must be level 2 headings.
Configuration Option Documentation
**********************************
Most of the ACRN documentation is maintained in ``.rst`` files found in the
``doc/`` folder. API documentation is maintained as Doxygen comments in the C
header files (or as kerneldoc comments in the ``acrn-kernel`` repo headers),
along with some prose documentation in ``.rst`` files. The ACRN configuration
option documentation is created based on details maintained in schema definition
files (``.xsd``) in the ``misc/config_tools/schema`` folder. These schema
definition files are used by the configuration tool to validate the XML scenario
configuration files as well as to hold documentation about each option. For
example:
.. code-block:: xml
<xs:element name="RELEASE" type="Boolean" default="n">
<xs:annotation>
<xs:documentation>Build an image for release (``y``) or debug (``n``).
In a **release** image, assertions are not enforced and debugging
features are disabled, including logs, serial console, and the
hypervisor shell.</xs:documentation>
</xs:annotation>
</xs:element>
During the documentation ``make html`` processing, the documentation annotations
in the ``.xsd`` files are extracted and transformed into restructureText using
an XSLT transformation found in ``doc/scripts/configdoc.xsl``. The generated
option documentation is organized and formatted to make it easy to created links
to specific option descriptions using an ``:option:`` role, for example
``:option:`hv.DEBUG_OPTIONS.RELEASE``` would link to
:option:`hv.DEBUG_OPTIONS.RELEASE`.
The transformed option documentation is
created in the ``_build/rst/reference/configdoc.txt`` file and included by
``doc/reference/config-options.rst`` to create the final published
:ref:`scenario-config-options` document. You make changes to the option
descriptions by editing the documentation found in one of the ``.xsd`` files.
Documentation Generation
************************