diff --git a/latest/_images/graphviz-610e90df782db1efad7efaa950d71fe85e3a7eb0.png b/latest/_images/graphviz-610e90df782db1efad7efaa950d71fe85e3a7eb0.png
deleted file mode 100644
index d961dc386..000000000
Binary files a/latest/_images/graphviz-610e90df782db1efad7efaa950d71fe85e3a7eb0.png and /dev/null differ
diff --git a/latest/_images/graphviz-8ed5ee208bfc9bfd5e031d90f119d55a1266d476.png b/latest/_images/graphviz-8ed5ee208bfc9bfd5e031d90f119d55a1266d476.png
new file mode 100644
index 000000000..6052b2121
Binary files /dev/null and b/latest/_images/graphviz-8ed5ee208bfc9bfd5e031d90f119d55a1266d476.png differ
diff --git a/latest/_images/graphviz-610e90df782db1efad7efaa950d71fe85e3a7eb0.png.map b/latest/_images/graphviz-8ed5ee208bfc9bfd5e031d90f119d55a1266d476.png.map
similarity index 100%
rename from latest/_images/graphviz-610e90df782db1efad7efaa950d71fe85e3a7eb0.png.map
rename to latest/_images/graphviz-8ed5ee208bfc9bfd5e031d90f119d55a1266d476.png.map
diff --git a/latest/_sources/developer-guides/doc_guidelines.rst.txt b/latest/_sources/developer-guides/doc_guidelines.rst.txt
index dcaf0ff14..1aab78388 100644
--- a/latest/_sources/developer-guides/doc_guidelines.rst.txt
+++ b/latest/_sources/developer-guides/doc_guidelines.rst.txt
@@ -3,20 +3,20 @@
Documentation Guidelines
########################
-OPEA Project content is written using the `markdown`_ (``.md``) with `MyST extensions`_ and `reStructuredText`_ markup
-language (``.rst``) with `Sphinx extensions`_, and processed
+OPEA Project content is written using the `markdown`_ (``.md``) with `MyST extensions`_
+and `reStructuredText`_ markup language (``.rst``) with `Sphinx extensions`_, and processed
using `Sphinx`_ to create a formatted stand-alone website. Developers can
-view this content either in its raw form as ``.md`` and ``.rst`` markup files, or (with
-Sphinx installed) they can build the documentation using the Makefile
-(on Linux systems) to generate the HTML content. The HTML content can then be
-viewed using a web browser. These ``.md`` and ``.rst`` files are maintained in
-the project's GitHub repos and processed to create the
-`OPEA Project documentation`_ website.
+view this content either in its raw form as ``.md`` and ``.rst`` markup files, or
+build the documentation locally following the :ref:`opea_doc_generation` instructions.
+The HTML content can then be viewed using a web browser. These ``.md`` and
+``.rst`` files are maintained in the project's GitHub repos and processed to
+create the `OPEA Project documentation`_ website.
.. note:: While GitHub supports viewing `.md` and `.rst` content with your browser on the
`github.com` site, markdown and reST extensions are not recognized there, so the
best viewing experience is through the `OPEA Project documentation`_ github.io
- website.
+ website. The github.io site also provides navigation and searching that makes
+ it easier to find and read what you're looking for.
You can read details about `reStructuredText`_ and `Sphinx extensions`_, and
`markdown`_ and `MyST extensions`_ from their respective websites.
@@ -31,14 +31,15 @@ You can read details about `reStructuredText`_ and `Sphinx extensions`_, and
This document provides a quick reference for commonly used markdown and reST
with MyST and Sphinx-defined directives and roles used to create the documentation
-you're reading.
+you're reading. It also provides best-known-methods for working with a mixture
+of reStructuredText and markdown.
Markdown vs. RestructuredText
*****************************
Both markdown and ReStructureText (reST) let you create individual documentation files that
GitHub can render when viewing them in your browser on github.com. Markdown is
-popular because of it's familarity with developers and is the default markup
+popular because of it's familiarity with developers and is the default markup
language for StackOverflow, Reddit, GitHub, and others. ReStructuredText came
from the Python community in 2001 and became noticed outside that
community with the release of Sphinx in 2008. These days, reST is supported by GitHub
@@ -47,7 +48,7 @@ OpenCV and LLVM/Clang.
ReStructuredText is more fully-featured, much more standardized and uniform, and
has built-in support for extensions. The markdown language has no standard way
-to implement complete documentation systems and doesnt have a standard extension
+to implement complete documentation systems and doesn't have a standard extension
mechanism, which leads to many different "flavors" of markdown. If you stick to
the core and common markdown syntax (headings, paragraphs, lists, and such),
using markdown is just fine. However, slipping in raw HTML to do formatting
@@ -59,15 +60,15 @@ markdown content within the OPEA project.
Within the OPEA documentation, we use both markdown and reST files for the
documentation "leaves". We rely on reST for the documentation organization trunk and
-branches, through the use of the reST toctree directives.
+branches, through the use of the reST ``toctree`` directives.
Documentation Organization
**************************
Documentation is maintained and updated the same as the project's code within
-the opea-project GitHub repos. There are many ``README.md`` files within the various
+the opea-project GitHub repos. There are many ``README.md`` and other markdown files within the various
repos along with the other files for those components. This is good because it
-keeps the relevent documentation and code for that component together.
+keeps the relevant documentation and code for that component together.
We use the ``docs`` repo to organize the presentation of all these ``README.md``
files, along with other project related documents that are maintained in the
@@ -79,6 +80,9 @@ directive to point to other documents that may include additional ``toctree``
directives of their own, ultimately collecting all the content into an
organizational structure you can navigate.
+Ultimately every document file (``.md`` and ``.rst``) in the project must appear
+in the ``toctree`` hierarchy. An orphan document file will be flagged by Sphinx
+as not included in a toctree directive.
Headings
********
@@ -156,7 +160,8 @@ Headings
intervening H2 ``##``. You may skip heading levels on the way back up,
for example, from an H4 ``####`` back up to an H2 ``##`` as appropriate.
-
+ Sphinx will complain if it finds multiple H1 headings or if you skip a
+ heading level.
Content Highlighting
@@ -180,12 +185,12 @@ Some common reST and markdown inline markup samples:
.. group-tab:: markdown
- * one back quote: ```text``` for `inline code` samples.
+ * one back quote: ```text``` for ``inline code`` samples.
For inline markup, the characters between
the beginning and ending characters must not start or end with a space,
so ``*this is italics*``, (*this is italics*) while ``* this isn't*``
-(* this isn't*).
+(* this isn't*) because of that extra space after the first asterisk.
If an asterisk or back quote appears in running text and could be confused
with inline markup delimiters, you can eliminate the confusion by adding a
@@ -203,16 +208,46 @@ should be indented at the same level as the preceding paragraph (and not
indented itself).
For numbered lists
-start with a ``1.`` or ``a)`` for example, and continue with autonumbering by
-using a ``#`` sign and a ``.`` or ``)`` as used in the first list item.
+start with a ``1.`` or ``a.`` for example, and continue with autonumbering by
+using a ``#`` sign and a ``.`` as used in the first list item.
Indent continuation lines with spaces to align with the text of first
list item:
+It's important to maintain the indentation of content under a list so in the
+generated HTML, the content looks like it's part of that list and not a new
+paragraph outside of that list.
+
+For example, compare this:
+
+-----
+
+* Here's a bullet list item
+
+Here's a paragraph that should be part of that first bullet list item's content.
+
+* Here's a second bullet list item
+
+-----
+
+Notice how that middle paragraph is out-dented from the bullet list compared
+with this next example where it's not (yes, it's subtle):
+
+-----
+
+* Here's a bullet list item
+
+ Here's a paragraph that does look like it's part of that first bullet list item's content because it's indented in the source.
+
+* Here's a second bullet list item
+
+-----
+
+
.. code-block:: rest
* This is a bulleted list.
* It has two items, the second
- item and has more than one line of reST text. Additional lines
+ item and has more than one line of text. Additional lines
are indented to the first character of the
text of the bullet list.
@@ -220,9 +255,9 @@ list item:
it would be a continuation of the previous list (or paragraph).
#. It has two items too.
- a) This is a numbered list using alphabetic list headings
- #) It has three items (and uses autonumbering for the rest of the list)
- #) Here's the third item. Use consistent punctuation on the list
+ a. This is a numbered list using alphabetic list headings
+ #. It has three items (and uses autonumbering for the rest of the list)
+ #. Here's the third item. Use consistent punctuation on the list
number.
#. This is an autonumbered list (default is to use numbers starting
@@ -234,74 +269,87 @@ list item:
#. And a second item back in the containing list. No blank line
needed, but it wouldn't hurt for readability.
-Definition lists (with one or more terms and their definition) are a
-convenient way to document a word or phrase with an explanation. For example,
-this reST content:
+.. tabs::
-.. code-block:: rest
+ .. group-tab:: reST
- The Makefile has targets that include:
+ Definition lists (with one or more terms and their definition) are a
+ convenient way to document a word or phrase with an explanation. For example,
+ this reST content:
- ``html``
- Build the HTML output for the project
+ .. code-block:: rest
+
+ The Makefile has targets that include:
+
+ ``html``
+ Build the HTML output for the project
- ``clean``
- Remove all generated output, restoring the folders to a
- clean state.
+ ``clean``
+ Remove all generated output, restoring the folders to a
+ clean state.
-Would be rendered as:
+ Would be rendered as:
- The Makefile has targets that include:
+ The Makefile has targets that include:
- html
- Build the HTML output for the project
+ html
+ Build the HTML output for the project
+
+ clean
+ Remove all generated output, restoring the folders to a
+ clean state.
+
+ .. group-tab:: markdown
- clean
- Remove all generated output, restoring the folders to a
- clean state.
+ Definition lists aren't directly supported by markdown.
Multi-Column Lists
******************
-In reST, 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
-special ``.. rst-class:: rst-columns`` directive. The directive will apply to
-the next non-comment element (for example, paragraph) or to content indented under
-the directive. For example, this unordered list::
-
- .. rst-class:: rst-columns
-
- * A list of
- * short items
- * that should be
- * displayed
- * horizontally
- * so it doesn't
- * use up so much
- * space on
- * the page
-
-would be rendered as:
-
-.. rst-class:: rst-columns
-
- * A list of
- * short items
- * that should be
- * displayed
- * horizontally
- * so it doesn't
- * use up so much
- * space on
- * the page
-
-A maximum of three columns will be displayed if you use ``rst-columns``
-(or ``rst-columns3``), and two columns for ``rst-columns2``. The number
-of columns displayed can be reduced based on the available width of the
-display window, reducing to one column on narrow (phone) screens if necessary.
-
-.. note:: We've deprecated use of the ``hlist`` directive because it
- misbehaves on smaller screens.
+.. tabs::
+
+ .. group-tab:: reST
+
+ In reST, 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
+ special ``.. rst-class:: rst-columns`` directive. The directive will apply to
+ the next non-comment element (for example, paragraph) or to content indented under
+ the directive. For example, this unordered list::
+
+ .. rst-class:: rst-columns
+
+ * A list of
+ * short items
+ * that should be
+ * displayed
+ * horizontally
+ * so it doesn't
+ * use up so much
+ * space on
+ * the page
+
+ would be rendered as:
+
+ .. rst-class:: rst-columns
+
+ * A list of
+ * short items
+ * that should be
+ * displayed
+ * horizontally
+ * so it doesn't
+ * use up so much
+ * space on
+ * the page
+
+ A maximum of three columns will be displayed if you use ``rst-columns``
+ (or ``rst-columns3``), and two columns for ``rst-columns2``. The number
+ of columns displayed can be reduced based on the available width of the
+ display window, reducing to one column on narrow (phone) screens if necessary.
+
+ .. group-tab:: markdown
+
+ Multi-column lists aren't directly supported by markdown.
Tables
******
@@ -311,7 +359,8 @@ There are a few ways to create tables, each with their limitations or quirks.
OPEA Project content is written using the markdown ( OPEA Project content is written using the markdown (Documentation Guidelines¶
-.md
) with MyST extensions and reStructuredText markup
-language (.rst
) with Sphinx extensions, and processed
+.md
) with MyST extensions
+and reStructuredText markup language (.rst
) with Sphinx extensions, and processed
using Sphinx to create a formatted stand-alone website. Developers can
-view this content either in its raw form as .md
and .rst
markup files, or (with
-Sphinx installed) they can build the documentation using the Makefile
-(on Linux systems) to generate the HTML content. The HTML content can then be
-viewed using a web browser. These .md
and .rst
files are maintained in
-the project’s GitHub repos and processed to create the
-OPEA Project documentation website..md
and .rst
markup files, or
+build the documentation locally following the OPEA Documentation Generation instructions.
+The HTML content can then be viewed using a web browser. These .md
and
+.rst
files are maintained in the project’s GitHub repos and processed to
+create the OPEA Project documentation website.
Note
While GitHub supports viewing .md and .rst content with your browser on the github.com site, markdown and reST extensions are not recognized there, so the best viewing experience is through the OPEA Project documentation github.io -website.
+website. The github.io site also provides navigation and searching that makes +it easier to find and read what you’re looking for.You can read details about reStructuredText and Sphinx extensions, and markdown and MyST extensions from their respective websites.
This document provides a quick reference for commonly used markdown and reST with MyST and Sphinx-defined directives and roles used to create the documentation -you’re reading.
+you’re reading. It also provides best-known-methods for working with a mixture +of reStructuredText and markdown.Both markdown and ReStructureText (reST) let you create individual documentation files that GitHub can render when viewing them in your browser on github.com. Markdown is -popular because of it’s familarity with developers and is the default markup +popular because of it’s familiarity with developers and is the default markup language for StackOverflow, Reddit, GitHub, and others. ReStructuredText came from the Python community in 2001 and became noticed outside that community with the release of Sphinx in 2008. These days, reST is supported by GitHub @@ -843,7 +844,7 @@
Documentation is maintained and updated the same as the project’s code within
-the opea-project GitHub repos. There are many README.md
files within the various
+the opea-project GitHub repos. There are many README.md
and other markdown files within the various
repos along with the other files for those components. This is good because it
-keeps the relevent documentation and code for that component together.
We use the docs
repo to organize the presentation of all these README.md
files, along with other project related documents that are maintained in the
docs
repo. The root of the generated documentation starts with the
@@ -870,6 +871,9 @@
Ultimately every document file (.md
and .rst
) in the project must appear
+in the toctree
hierarchy. An orphan document file will be flagged by Sphinx
+as not included in a toctree directive.
##
. You may skip heading levels on the way back up,
for example, from an H4 ####
back up to an H2 ##
as appropriate.
+Sphinx will complain if it finds multiple H1 headings or if you skip a +heading level.
one back quote: `text`
for inline code samples.
one back quote: `text`
for inline code
samples.
For inline markup, the characters between
the beginning and ending characters must not start or end with a space,
so *this is italics*
, (this is italics) while * this isn't*
-(* this isn’t*).
If an asterisk or back quote appears in running text and could be confused
with inline markup delimiters, you can eliminate the confusion by adding a
backslash (\
) before it.
For numbered lists
-start with a 1.
or a)
for example, and continue with autonumbering by
-using a #
sign and a .
or )
as used in the first list item.
+start with a 1.
or a.
for example, and continue with autonumbering by
+using a #
sign and a .
as used in the first list item.
Indent continuation lines with spaces to align with the text of first
list item:
It’s important to maintain the indentation of content under a list so in the +generated HTML, the content looks like it’s part of that list and not a new +paragraph outside of that list.
+For example, compare this:
+Here’s a bullet list item
Here’s a paragraph that should be part of that first bullet list item’s content.
+Here’s a second bullet list item
Notice how that middle paragraph is out-dented from the bullet list compared +with this next example where it’s not (yes, it’s subtle):
+Here’s a bullet list item
+Here’s a paragraph that does look like it’s part of that first bullet list item’s content because it’s indented in the source.
+Here’s a second bullet list item
* This is a bulleted list.
* It has two items, the second
- item and has more than one line of reST text. Additional lines
+ item and has more than one line of text. Additional lines
are indented to the first character of the
text of the bullet list.
@@ -988,9 +1017,9 @@ Lists¶
it would be a continuation of the previous list (or paragraph).
#. It has two items too.
-a) This is a numbered list using alphabetic list headings
-#) It has three items (and uses autonumbering for the rest of the list)
-#) Here's the third item. Use consistent punctuation on the list
+a. This is a numbered list using alphabetic list headings
+#. It has three items (and uses autonumbering for the rest of the list)
+#. Here's the third item. Use consistent punctuation on the list
number.
#. This is an autonumbered list (default is to use numbers starting
@@ -1003,7 +1032,8 @@ Lists¶
needed, but it wouldn't hurt for readability.
Definition lists (with one or more terms and their definition) are a +
Definition lists (with one or more terms and their definition) are a convenient way to document a word or phrase with an explanation. For example, this reST content:
The Makefile has targets that include:
@@ -1027,10 +1057,13 @@ Lists¶
Definition lists aren’t directly supported by markdown.
+In reST, if you have a long bullet list of items, where each item is short, you can +
In reST, 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
special .. rst-class:: rst-columns
directive. The directive will apply to
the next non-comment element (for example, paragraph) or to content indented under
@@ -1064,11 +1097,8 @@
rst-columns2
. The number
of columns displayed can be reduced based on the available width of the
display window, reducing to one column on narrow (phone) screens if necessary.
-Note
-We’ve deprecated use of the hlist
directive because it
-misbehaves on smaller screens.
Multi-column lists aren’t directly supported by markdown.
++------------------------+------------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
@@ -1125,7 +1156,8 @@ Tables¶
-For reST, List tables
+
+For reST, List tables
are much easier to maintain, but don’t support row or column spans:
.. list-table:: Table title
:widths: 15 20 40
@@ -1173,11 +1205,43 @@ Tables¶
columns, you can specify :widths: 1 2 2
. If you’d like the browser
to set the column widths automatically based on the column contents, you
can use :widths: auto
.
+
Markdown also supports a more free-form table syntax where the rigid box
+alignment is greatly simplified as explained in
+markdown tables.
+Use three or more hyphens ---
to denote each column’s header, and use
+pipes |
to separate each column. For compatibility you should also
+add a pipe on both ends of the row:
+| heading 1 | heading 2 | heading 3 |
+|---|---|---|
+|row 1 column 1 | row 1 column 2 | yes, it's row 1 column 3|
+|row 2 col 1 | row 2 column 2 | row 2 col 3 |
+
+
+That would be rendered as:
+
+
+heading 1
+heading 2
+heading 3
+
+
+
+row 1 column 1
+row 1 column 2
+yes, it’s row 1 column 3
+
+row 2 col 1
+row 2 column 2
+row 2 col 3
+
+
+
+
File Names and Commands¶
-Sphinx extends reST by supporting additional inline markup elements (called
+
Sphinx extends reST by supporting additional inline markup elements (called
“roles”) used to tag text with special meanings and enable output formatting.
(You can refer to the Sphinx Inline Markup documentation for the full
list).
@@ -1187,7 +1251,7 @@ File Names and Commandsfilename.
Don’t use items within a single backtick, for example `word`
. Instead
use double backticks: ``word``
.
-
MyST extends markdown by supporting additional inline markup elements
+
MyST extends markdown by supporting additional inline markup elements
(called “roles”) used to tag text with special meanings and enable output
formatting.
@@ -1224,7 +1288,7 @@ Branch-Specific File Links
Internal Cross-Reference Linking¶
-Traditional reST links are supported only within the current file using the
+
Traditional reST links are supported only within the current file using the
notation:
refer to the `internal-linking`_ documentation
@@ -1278,7 +1342,50 @@ Branch-Specific File Links:ref:`alternate text <doc_guidelines>` (renders as
alternate text).
-
TODO
+Linking from a reST document to a markdown document is done using the reST
+:doc:
role, and using the path to the markdown file leaving off the
+.md
file extension. For example:
+Refer to the :doc:`/GenAIExamples/supported_examples` list for details.
+
+
+Note that all the markdown files from all the repos are available with
+this syntax because we copy all those files into the doc building folder
+under a top-level directory with that repo’s name. Markdown files in the
+docs repo don’t use the docs
repo name as the path root but use /
+instead. So to link to the contribution guide markdown file found in the
+docs repo community directory you would use :doc:`Contribution Guide
+</community/CONTRIBUTING>`
. Notice you can change the link text using
+the normal reST role syntax shown here.
+Markdown supports linking to other documents using the [link text](link path)
.
+For example to link to a document within the same repo, a relative path is
+used:
+Refer to [Kubernetes deployment](./kubernetes/intel/README_gmc.md)
+
+
+That reference is rendered as a reference to the README_gmc.html found in
+the directory kubernetes/intel
relative to the document doing the
+linking.
+References to documents in other repos within the OPEA project are made
+using an URL to the document in the github.com repo as it would be found
+in a web browser. For example, from a markdown document in the
+GenAIExamples repo referencing a document in the GenAIInfra repo:
+Refer to the [DocSum helm chart](https://github.com/opea-project/GenAIInfra/tree/main/helm-charts/docsum/README.md)
+for instructions on deploying DocSum into Kubernetes on Xeon & Gaudi.
+
+
+That reference would be rendered into a reference to the
+https://opea-project.github.io/GenAIInfra/helm-charts/docsum/README.html
+document within the github.io website.
+Markdown supports linking to a reST document by using the Myst syntax that
+mimics the way reST documents link to each other using the :ref:
role
+and using the label at the beginning of the reST document. For example:
+{ref}`ChatQnA Example Deployment Options <chatqna-example-deployment>`
+
+
+The ChatQnA example deployment options document found at
+examples/ChatQnA/deploy/index.rst
has that
+chatqna-example-deployment
label at the top we can
+reference instead of knowing the path to the document.
@@ -1331,7 +1438,7 @@ Non-ASCII Characters
-In reST, you incorporate content from another file using an include
+
In reST, you incorporate content from another file using an include
directive. Unless options are given, the included file is parsed in the
current document’s context:
Here is some text in the reST document.
@@ -1351,16 +1458,16 @@ Non-ASCII Characters:parser: myst_parser.sphinx_ if the included file is markdown.
-:start-after: text Only the content after the first occurance of the specified text
in
+
:start-after: text Only the content after the first occurrence of the specified text
in
the external file will be included.
-:end-before: Only the content before the first occurance of the specified text
+
:end-before: Only the content before the first occurrence of the specified text
in the external file will be included.
These and other options described in the docutils include directive
documentation.
-
+
MyST directives can be used to incorporate content from another file
into the current document as if it were part of the current document:
```{include} relativepath/to/file
@@ -1393,7 +1500,7 @@ Non-ASCII Characters
Code and Command Examples¶
-Use the reST code-block
directive to create a highlighted block of
+
Use the reST code-block
directive to create a highlighted block of
fixed-width text, typically used for showing formatted code or console
commands and output. Smart syntax highlighting is also supported (using the
Pygments package). You can also directly specify the highlighting language.
@@ -1445,7 +1552,7 @@
Code and Command ExamplesIn markdown, fenced code blocks are used to define code blocks. Use three
+
In markdown, fenced code blocks are used to define code blocks. Use three
backticks ```
on the lines before and after the code block, for
example:
```
@@ -1497,7 +1604,7 @@ Images¶
250 KB unless a particularly large image is needed for clarity.
You can also specify an URL to an image file if needed.
-In reST, images are placed the document using an image directive:
+In reST, images are placed the document using an image directive:
.. image:: ../images/opea-horizontal-color-w200.png
:align: center
:alt: alt text for the image
@@ -1510,7 +1617,7 @@ Images¶
Caption for the figure
-
+
In markdown, images are placed in documentation using this syntax:
![OPEA Logo](../images/opea-horizontal-color-w200.png)
@@ -1551,10 +1658,10 @@ Background Colors
Drawings¶
-In reST, we’ve included the graphviz
Sphinx extension to enable that
+
In reST, we’ve included the graphviz
Sphinx extension to enable that
text description language to render drawings. For more information, see
Drawings Using Graphviz.
-We’v ealso included an extension providing mermaid
support that also enables
+
We’ve also included an extension providing mermaid
support that also enables
that text description language to render drawings using:
.. mermaid::
@@ -1572,7 +1679,7 @@ Drawings
C--> A & B;
See the Mermaid User Guide for more
information.
-In markdown, we’ve included the MyST mermaid
extensions to enable that text
+
In markdown, we’ve included the MyST mermaid
extensions to enable that text
description language to render drawings using:
```{mermaid}
graph LR;
@@ -1598,7 +1705,7 @@ Drawings
Alternative Tabbed Content¶
-In ResST, instead of creating multiple documents with common material except for some
+
In reST, instead of creating multiple documents with common material except for some
specific sections, you can write one document and provide alternative content
to the reader via a tabbed interface. When the reader clicks a tab, the
content for that tab is displayed. For example:
@@ -1619,21 +1726,21 @@ Alternative Tabbed Content
-Apples are green, or sometimes red.
-Pears are green.
-Oranges are orange.
+Apples are green, or sometimes red.
+Pears are green.
+Oranges are orange.
Tabs can also be grouped so that changing the current tab in one area
changes all tabs with the same name throughout the page. For example:
-Linux Line 1
-macOS Line 1
-Windows Line 1
+Linux Line 1
+macOS Line 1
+Windows Line 1
-Linux Line 2
-macOS Line 2
-Windows Line 2
+Linux Line 2
+macOS Line 2
+Windows Line 2
In this latter case, we’re using a .. group-tab::
directive instead of
a .. tab::
directive. Under the hood, we’re using the sphinx-tabs extension that’s included
diff --git a/latest/developer-guides/docbuild.html b/latest/developer-guides/docbuild.html
index a7a7e6e9c..792b75e92 100644
--- a/latest/developer-guides/docbuild.html
+++ b/latest/developer-guides/docbuild.html
@@ -825,24 +825,26 @@
Documentation Overview¶
OPEA project content is written using combination of markdown (.md
) and
-reStructuredText (.rst
) markup languages (with Sphinx extensions), and
-processed using Sphinx to create a formatted stand-alone website. Developers can
-view this content either in its raw form as .rst markup files, or you can
-generate the HTML content and view it with a web browser directly on your
-workstation. The best reading experience is by viewing the generated HTML at
-https://opea-project.github.io.
+reStructuredText (.rst
) markup languages (with Sphinx extensions such as
+Myst), and
+processed using Sphinx to create a formatted stand-alone website.
+The best reading experience is by viewing the generated HTML at
+https://opea-project.github.io.
+While working on new content or editing existing content, developers can
+generate the HTML content locally and view it with a web browser.
You can read details about markdown, reStructuredText, and Sphinx from
their respective websites.
-The project’s documentation contains the following items:
-
-ReStructuredText and markdown source files used to generate documentation found at the
-https://opea-project.github.io website. All of the documentation sources
-are found in the github.com/opea-project
repos, rooted in the docs
repo.
-There’s also documentation in the repos where the project’s code is
-maintained: GenAIComps
, GenAIEval
, GenAIExamples
, and GenAIInfra
.
-
+The project’s documentation is a collection of ReStructuredText and markdown
+source files used to generate documentation found at the
+https://opea-project.github.io website. All of the documentation sources are
+found in the github.com/opea-project
project repos, organized and rooted in
+the docs
repo. Much of the detailed documentation lives in the repos where
+the project’s code is maintained: GenAIComps
, GenAIEval
,
+GenAIExamples
, and GenAIInfra
. The documentation generation process
+collects all the needed files from all these repos into one building area to
+create the final generated HTML.