github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-21 21:19:35 +00:00
Code Issues Projects Releases Wiki Activity

doc: Style cleanup in doc guides

Browse Source 
- Minor style changes per Acrolinx recommendations

Signed-off-by: Reyes, Amy <amy.reyes@intel.com>
This commit is contained in:
Reyes, Amy 2022-02-18 17:26:38 -08:00 committed by David Kinder
parent 97855c54c2
commit dc207b3fa3
2 changed files with 32 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -166,7 +166,7 @@ Multi-Column Lists
If you have a long bullet list of items, where each item is short, you can If you have a long bullet list of items, where each item is short, you can
indicate that the list items should be rendered in multiple columns with a indicate that the list items should be rendered in multiple columns with a
special ``.. rst-class:: rst-columns`` directive. The directive will apply to special ``.. rst-class:: rst-columns`` directive. The directive will apply to
the next non-comment element (e.g., paragraph) or to content indented under the next non-comment element (for example, paragraph) or to content indented under
the directive. For example, this unordered list:: the directive. For example, this unordered list::
.. rst-class:: rst-columns .. rst-class:: rst-columns
@ -300,11 +300,11 @@ use double backticks: ````word````.
Branch-Specific File Links Branch-Specific File Links
************************** **************************
Links in the documentation to specific files in the GitHub tree should also be You can add a link in the documentation to a specific file in the GitHub tree.
to the branch for that version of the documentation (e.g., links in the v2.5 Be sure the link points to the branch for that version of the documentation. For
release of the documentation should be to files in the v2.5 branch). You should example, links in the v2.5 release of the documentation should be to files in
not link to files in the master branch because files in that branch could change the v2.5 branch. Do not link to files in the master branch because files in that
or even be deleted after the release is made. branch could change or even be deleted after the release is made.
To make this kind of file linking possible, use a special role that To make this kind of file linking possible, use a special role that
creates a hyperlink to that file in the current branch. For example, a GitHub creates a hyperlink to that file in the current branch. For example, a GitHub
@ -314,12 +314,12 @@ appear as :acrn_file:`doc/developer-guides/doc_guidelines.rst`, a link to
the "blob" file in the GitHub repo as displayed by GitHub. There's also an the "blob" file in the GitHub repo as displayed by GitHub. There's also an
``:acrn_raw:`doc/developer-guides/doc_guidelines.rst``` role that will link ``:acrn_raw:`doc/developer-guides/doc_guidelines.rst``` role that will link
to the "raw" uninterpreted file, to the "raw" uninterpreted file,
:acrn_raw:`doc/developer-guides/doc_guidelines.rst` file. (Click these links :acrn_raw:`doc/developer-guides/doc_guidelines.rst`. Click these links
to see the difference.) to see the difference.
If you don't want the whole path to the file name to If you don't want the whole path to the file name to
appear in the text, you use the usual linking notation to define what link text appear in the text, you use the usual linking notation to define what link text
is shown, for example ``:acrn_file:`Guidelines <doc/developer-guides/doc_guidelines.rst>``` is shown, for example, ``:acrn_file:`Guidelines <doc/developer-guides/doc_guidelines.rst>```
would show up as simply :acrn_file:`Guidelines <doc/developer-guides/doc_guidelines.rst>`. would show up as simply :acrn_file:`Guidelines <doc/developer-guides/doc_guidelines.rst>`.
.. _internal-linking: .. _internal-linking:
@ -342,7 +342,7 @@ Note the use of a trailing underscore to indicate an outbound link. In this
example, the label was added immediately before a heading, so the text that's example, the label was added immediately before a heading, so the text that's
displayed is the heading text itself. displayed is the heading text itself.
With Sphinx however, we can create link-references to any tagged text within With Sphinx, however, we can create link-references to any tagged text within
the project documentation. the project documentation.
Target locations within documents are defined with a label directive: Target locations within documents are defined with a label directive:
@ -355,9 +355,9 @@ Note the leading underscore indicating an inbound link. The content
immediately following this label is the target for a ``:ref:`my label name``` immediately following this label is the target for a ``:ref:`my label name```
reference from anywhere within the documentation set. The label **must** be reference from anywhere within the documentation set. The label **must** be
added immediately before a heading so that there's a natural phrase to show added immediately before a heading so that there's a natural phrase to show
when referencing this label (e.g., the heading text). when referencing this label (for example, the heading text).
This is the same directive used to define a label that's a reference to a URL: This directive is also used to define a label that's a reference to a URL:
.. code-block:: rest .. code-block:: rest
@ -435,7 +435,7 @@ Note that there is a blank line between the ``code-block`` directive and the
first line of the code-block body, and the body content is indented three first line of the code-block body, and the body content is indented three
spaces (to the first non-blank space of the directive name). spaces (to the first non-blank space of the directive name).
This would be rendered as: This example would render as:
.. code-block:: c .. code-block:: c
@ -456,14 +456,14 @@ If you want no syntax highlighting, specify ``none``. For example:
.. code-block:: none .. code-block:: none
This would be a block of text styled with a background This block of text would be styled with a background
and box, but with no syntax highlighting. and box, but with no syntax highlighting.
Would display as: Would display as:
.. code-block:: none .. code-block:: none
This would be a block of text styled with a background This block of text would be styled with a background
and box, but with no syntax highlighting. and box, but with no syntax highlighting.
There's a shorthand for writing code blocks, too: end the introductory There's a shorthand for writing code blocks, too: end the introductory
@ -471,7 +471,7 @@ paragraph with a double colon (``::``) and indent the code block content
by three spaces. On output, only one colon will appear. by three spaces. On output, only one colon will appear.
.. note:: The highlighting package makes a best guess at the type of content .. note:: The highlighting package makes a best guess at the type of content
in the block for highlighting purposes. This can lead to some odd in the block, which can lead to odd
highlighting in the generated output. highlighting in the generated output.
Images Images
@ -518,7 +518,7 @@ in the preceding line. For example:
The text within a directive block should align with the The text within a directive block should align with the
first character of the directive name. first character of the directive name.
Keep the line length for documentation less than 80 characters to make it Keep the line length for documentation fewer than 80 characters to make it
easier for reviewing in GitHub. Long lines due to URL references are an easier for reviewing in GitHub. Long lines due to URL references are an
allowed exception. allowed exception.
@ -617,7 +617,7 @@ Alternative Tabbed Content
Instead of creating multiple documents with common material except for some Instead of creating multiple documents with common material except for some
specific sections, you can write one document and provide alternative content specific sections, you can write one document and provide alternative content
to the reader via a tabbed interface. When the reader clicks on a tab, the to the reader via a tabbed interface. When the reader clicks a tab, the
content for that tab is displayed. For example:: content for that tab is displayed. For example::
.. tabs:: .. tabs::
@ -761,7 +761,7 @@ to specific option descriptions using an ``:option:`` role, for example,
The transformed option documentation is The transformed option documentation is
created in the ``_build/rst/reference/configdoc.txt`` file and included by created in the ``_build/rst/reference/configdoc.txt`` file and included by
``doc/reference/config-options.rst`` to create the final published ``doc/reference/config-options.rst`` to create the final published
:ref:`scenario-config-options` document. You make changes to the option :ref:`scenario-config-options` document. You modify the option
descriptions by editing the documentation found in one of the ``.xsd`` files. descriptions by editing the documentation found in one of the ``.xsd`` files.

20
doc/developer-guides/graphviz.rst
View File

@ -3,7 +3,7 @@
Drawings Using Graphviz Drawings Using Graphviz
####################### #######################
We support using the Sphinx `graphviz extension`_ for creating simple We support using the Sphinx `Graphviz extension`_ for creating simple
graphs and line drawings using the dot language. The advantage of using graphs and line drawings using the dot language. The advantage of using
Graphviz for drawings is that the source for a drawing is a text file that Graphviz for drawings is that the source for a drawing is a text file that
can be edited and maintained in the repo along with the documentation. can be edited and maintained in the repo along with the documentation.
@ -24,7 +24,7 @@ where the boot-flow.dot file contains the drawing commands:
.. literalinclude:: images/boot-flow.dot .. literalinclude:: images/boot-flow.dot
and the generated output would appear as this: and the generated output would appear as:
.. graphviz:: images/boot-flow.dot .. graphviz:: images/boot-flow.dot
:name: boot-flow-example :name: boot-flow-example
@ -51,7 +51,7 @@ graph (digraph) with two nodes connected by an arrow, you can write:
"a" -> "b" "a" -> "b"
} }
and get this: and get this drawing:
.. graphviz:: .. graphviz::
@ -60,10 +60,16 @@ and get this:
} }
You can change the graph layout (from top-to-bottom to left-to-right), node You can change the following attributes:
shapes (rectangles, circles, house, star, etc.), style (filled, rounded),
and colors, along with the text displayed in the node, and the resulting * Graph layout (from top-to-bottom to left-to-right)
image placement on the page (centered): * Node shapes (rectangles, circles, houses, stars, etc.)
* Style (filled, rounded)
* Colors
* Text displayed in the node
* Placement of the resulting image on the page (centered)
Example:
.. literalinclude:: images/circle-square.dot .. literalinclude:: images/circle-square.dot