doc: add more to doc guidelines and build (#180)

Signed-off-by: David B. Kinder <[email protected]>
opea-project · Sep 25, 2024 · c54469c · c54469c
1 parent 76ad1f4
commit c54469c
Show file tree

Hide file tree

Showing 8 changed files with 190 additions and 1,010 deletions.
diff --git a/community/CONTRIBUTING.md b/community/CONTRIBUTING.md
@@ -370,7 +370,7 @@ The OPEA projects use GitHub Action for CI test.
 - End to End Test, the PR must pass all end to end tests.
 
 #### Pull Request Review
-You can add reviewers from [the code owners list](../codeowner.md) to your PR.
+You can add reviewers from [the code owners list](./codeowner.md) to your PR.
 
 ## Support
 

diff --git a/community/ContributionGuidelines.txt b/community/ContributionGuidelines.txt
diff --git a/developer-guides/doc_guidelines.rst b/developer-guides/doc_guidelines.rst
@@ -34,6 +34,12 @@ with MyST and Sphinx-defined directives and roles used to create the documentati
 you're reading. It also provides best-known-methods for working with a mixture
 of reStructuredText and markdown.
 
+.. rst-class:: rst-columns
+
+.. contents::
+   :local:
+   :depth: 1
+
 Markdown vs. RestructuredText
 *****************************
 
@@ -652,6 +658,7 @@ We've kept the substitutions list small but you can add others as needed by
 submitting a change to the ``substitutions.txt`` file.
 
 Include Content from Other Files
+********************************
 
 You can directly incorporate a document fragment from another file into your reST or
 markdown content by using an ``include`` directive.
@@ -701,6 +708,18 @@ markdown content by using an ``include`` directive.
       These and other options described in the `docutils include directive <https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment>`_
       documentation.
 
+      As a practical example, here's how you could include markdown content into
+      a reST document, and have that included content interpreted as markdown.
+      Note that Sphinx will complain if it finds a .md or .rst file that's not
+      included in a toctree directive, it's bese to us a .txt extension for
+      included files::
+
+         .. include:: mdtable.txt
+            :parser: myst_parser.sphinx_
+
+      That's how we showed how a more free-form markdown table syntax would be
+      rendered in another part of this document.
+
    .. group-tab:: markdown
 
          MyST directives can be used to incorporate content from another file
@@ -848,7 +867,10 @@ Code and Command Examples
             "age": 25
          }
 
-      TODO: add the list of supported languages.
+      Commonly used languages are: ``bash``, ``console``, ``none``, ``json``,
+      ``python``, ``markdown``, and ``rest``.  See this
+      `complete list of Pygments lexer languages <https://pygments.org/docs/lexers>`_
+      for more (use the "Short name" shown).
 
 Images
 ******
@@ -993,78 +1015,126 @@ Drawings
 Alternative Tabbed Content
 **************************
 
-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::
+.. tabs::
+
+   .. group-tab:: reST
 
-   .. tabs::
+      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::
 
-      .. tab:: Apples
+         .. tabs::
 
-         Apples are green, or sometimes red.
+            .. tab:: Apples
 
-      .. tab:: Pears
+               Apples are green, or sometimes red.
 
-         Pears are green.
+            .. tab:: Pears
 
-      .. tab:: Oranges
+               Pears are green.
 
-         Oranges are orange.
+            .. tab:: Oranges
 
-will display as:
+               Oranges are orange.
 
-.. tabs::
+      will display as:
 
-   .. tab:: Apples
+      .. tabs::
 
-      Apples are green, or sometimes red.
+         .. tab:: Apples
 
-   .. tab:: Pears
+            Apples are green, or sometimes red.
 
-      Pears are green.
+         .. tab:: Pears
 
-   .. tab:: Oranges
+            Pears are green.
 
-      Oranges are orange.
+         .. tab:: Oranges
 
-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:
+            Oranges are orange.
 
-.. tabs::
+      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:
 
-   .. group-tab:: Linux
+      .. tabs::
 
-      Linux Line 1
+         .. group-tab:: Linux
 
-   .. group-tab:: macOS
+            Linux Line 1
 
-      macOS Line 1
+         .. group-tab:: macOS
 
-   .. group-tab:: Windows
+            macOS Line 1
 
-      Windows Line 1
+         .. group-tab:: Windows
 
-.. tabs::
+            Windows Line 1
+
+      .. tabs::
+
+         .. group-tab:: Linux
 
-   .. group-tab:: Linux
+            Linux Line 2
 
-      Linux Line 2
+         .. group-tab:: macOS
 
-   .. group-tab:: macOS
+            macOS Line 2
 
-      macOS Line 2
+         .. group-tab:: Windows
 
-   .. group-tab:: Windows
+            Windows 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
+      <https://github.com/djungelorm/sphinx-tabs>`_ extension that's included
+      in the OPEA docs (requirements.txt)  setup.  Within a tab, you can have most
+      any content *other than a heading* (code-blocks, ordered and unordered
+      lists, pictures, paragraphs, and such).
+
+   .. group-tab:: markdown
+
+      While markdown does not have native support for tabbed alternatives, we do
+      support this in the OPEA markdown documentation with the Myst Parser
+      extension::
+
+         ::::{tab-set}
+
+         :::{tab-item} Linux
+         :sync: Linux
+
+         This content will show on the Linux tab
+         :::
+         :::{tab-item} macOS
+         :sync: macOS
+
+         This content will show on the macOS tab
+         :::
+         :::{tab-item} Windows
+         :sync: Windows
+
+         This content will show on the Windows tab
+         :::
+         ::::
+
+      Each ``tab-set`` used a ``tab-item`` for each tabbed alternative. Adding
+      the ``:sync: <tabname>`` option causes all ``tab-set`` that share that
+      ``tab-item`` name to be synchronized through the document (all the tabs
+      will change to the selected tab).
+
+      Note the use of three colons as the fence instead of the normal use of
+      three backticks.  This allows use of three backtics within a tab for
+      denoting a code block.  Also note how nested colon fences are used with
+      four colons for the ``tab-set``, and that each colon
+      fence must be terminated with a matching colon fence because indenting is
+      not used for content within the fenced area (normal for markdown).
+
+      Here's what that would look like with two sets of tabbed alternative
+      content:
+
+      .. include:: tabbed-alternative.txt
+         :parser: myst_parser.sphinx_
 
-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
-<https://github.com/djungelorm/sphinx-tabs>`_ extension that's included
-in the OPEA docs (requirements.txt)  setup.  Within a tab, you can have most
-any content *other than a heading* (code-blocks, ordered and unordered
-lists, pictures, paragraphs, and such).
 
 Instruction Steps
 *****************

diff --git a/developer-guides/docbuild.rst b/developer-guides/docbuild.rst
@@ -7,6 +7,8 @@ These instructions walk you through generating the OPEA project documentation
 and publishing it to https://opea-project.github.io.  You can also use these
 instructions to generate the OPEA documentation on your local system.
 
+.. rst-class:: rst-columns
+
 .. contents::
    :local:
    :depth: 1
@@ -61,6 +63,11 @@ Some content is manipulated or generated during the doc build process:
   self-updated when new microservices are added to the GenAIComps/comps
   directory.
 
+- The CODEOWNERS files in the repos, containing the list of responsible
+  reviewers for those repos, are processed into a nice looking table included in
+  the ``community/codeowners.md`` document.  That way the list of project code
+  owners is kept in sync with what's in the CODEOWNERS files used by GitHub.
+
 - References in markdown files to markdown files (.md file extension) are
   converted to the corresponding generated HTML files by Sphinx using the Myst and
   sphinx-md extensions.

diff --git a/developer-guides/index.rst b/developer-guides/index.rst
@@ -17,7 +17,6 @@ Documentation Guides
 ********************
 
 .. toctree::
-   :maxdepth: 1
 
    doc_guidelines
    graphviz

diff --git a/developer-guides/tabbed-alternative.txt b/developer-guides/tabbed-alternative.txt
@@ -0,0 +1,43 @@
+Here's an example of markdown with two tab sets that are synchronized when
+chosen by the viewer:
+
+::::{tab-set}
+
+:::{tab-item} Linux
+:sync: Linux
+
+This content will show on the Linux tab
+:::
+:::{tab-item} macOS
+:sync: macOS
+
+This content will show on the macOS tab
+:::
+:::{tab-item} Windows
+:sync: Windows
+
+This content will show on the Windows tab
+:::
+::::
+
+Some more content here followed by another tab set:
+
+::::{tab-set}
+
+:::{tab-item} Linux
+:sync: Linux
+
+This is more content that will show on this Linux tab
+:::
+:::{tab-item} macOS
+:sync: macOS
+
+This is more content that will show on this macOS tab
+:::
+:::{tab-item} Windows
+:sync: Windows
+
+This is more content that will show on this Windows tab
+:::
+::::
+
diff --git a/scripts/sync-all-repos.sh b/scripts/sync-all-repos.sh
@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# synch local copy and origin with what's in upstream repo
+# assumes there's an origin and upstream remote defined in each of the repos
+
+# optionally, you can give a branch name as a first parameter and it will
+# checkout and sync all the repos to that branchname
+
+branch=${1:-main}
+
+for d in GenAIComps GenAIExamples GenAIEval GenAIInfra docs opea-project.github.io ; do
+    cd ~/opea-project/"$d"
+    echo "====" $d
+    git checkout $branch
+    git fetch upstream
+    git merge upstream/$branch
+    git push origin $branch
+done