doc: a few last doc tweaks

- change docs repo README to references opea-project.github.io (previous
  content has been incorporated elsewhere)
- add links to charter (moved from GOVERNANCE repo earlier) to TSC list
- tweak presentation of GenAIInfra (deploy) material
- fix subheading depth in developer-guides
- add troubleshooting section to docbuild guide

Signed-off-by: David B. Kinder <[email protected]>

README.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+OPEA Project Documentation
+##########################
+
+This repository holds the source and configuration files used to generate the
+`OPEA Project documentation web site`_ from all the documentation maintained in
+this docs repo and all the GenAI\* repos.
+
+.. _OPEA Project documentation web site: https://opea-project.github.io

community/charter.md

@@ -14,7 +14,7 @@ This Charter sets forth the responsibilities and procedures for technical contri
 ## 2. Technical Steering Committee
 
    1. The Technical Steering Committee (the “TSC”) will be responsible for all technical oversight of the open source Project.
-   2. The TSC voting members are initially those individuals listed as voting members of the TSC in the GOVERNANCE.MD file in the Project’s governance repo (moved to community/TSC.rst in the docs repo). At the inception of the project, the Maintainers of the Project will be as set forth within the “CONTRIBUTING” file within the Project’s code repository. The TSC may choose an alternative approach for determining the voting members of the TSC, and any such alternative approach will be documented in the GOVERNANCE file (now the TSC.rst file).  The Project intends to determine additional details on composition of the TSC to enable increased diversity of organizations represented on the TSC within 12 months following the inception of the Project, or such other time as determined by the TSC (the “Steady State Transition”).  The TSC expects to have no one company employing more than 50% of the voting members of the TSC by the Steady State Transition.  It is expected that the terms of TSC voting members will vary initially (with roughly half 1 year and the remainder 2 years)  so that elections will be staggered.  Any meetings of the Technical Steering Committee are intended to be open to the public, and can be conducted electronically, via teleconference, or in person.
+   2. The TSC voting members are initially those individuals listed as voting members of the TSC in the GOVERNANCE.MD file in the Project’s governance repo (moved to [community/TSC.rst](TSC.rst) in the docs repo). At the inception of the project, the Maintainers of the Project will be as set forth within the “CONTRIBUTING” file within the Project’s code repository. The TSC may choose an alternative approach for determining the voting members of the TSC, and any such alternative approach will be documented in the GOVERNANCE file (now the [TSC.rst](TSC.rst) file).  The Project intends to determine additional details on composition of the TSC to enable increased diversity of organizations represented on the TSC within 12 months following the inception of the Project, or such other time as determined by the TSC (the “Steady State Transition”).  The TSC expects to have no one company employing more than 50% of the voting members of the TSC by the Steady State Transition.  It is expected that the terms of TSC voting members will vary initially (with roughly half 1 year and the remainder 2 years)  so that elections will be staggered.  Any meetings of the Technical Steering Committee are intended to be open to the public, and can be conducted electronically, via teleconference, or in person.
    3. TSC projects generally will involve Contributors and Maintainers. The TSC may adopt or modify roles so long as the roles are documented in the CONTRIBUTING file. Unless otherwise documented:
       1. Contributors include anyone in the technical community that contributes code, documentation, or other technical artifacts to the Project;
       2. Maintainers are Contributors who have earned the ability to modify (“commit” or merge pull requests) source code, documentation or other technical artifacts in a project’s repository; and

community/index.rst

@@ -49,13 +49,9 @@ Contributing Guides
 .. toctree::
    :maxdepth: 1
 
-   ../README
    CONTRIBUTING
    codeowner
    SECURITY
-   ../developer-guides/doc_guidelines
-   ../developer-guides/docbuild
-   ../developer-guides/graphviz
 
 Roadmaps
 ********

deploy/index.rst

@@ -10,6 +10,7 @@ can deploy to their own cloud.
 We're building this documentation from content in the
 :GenAIInfra_blob:`GenAIInfra<README.md>` GitHub repository.
 
+.. rst-class:: rst-columns
 
 .. toctree::
    :maxdepth: 1
@@ -21,6 +22,8 @@ We're building this documentation from content in the
 Installation Guides
 *******************
 
+.. rst-class:: rst-columns
+
 .. toctree::
    :maxdepth: 1
    :glob:
@@ -31,6 +34,8 @@ Installation Guides
 Authentication and Authorization
 ********************************
 
+.. rst-class:: rst-columns
+
 .. toctree::
    :maxdepth: 1
    :glob:
@@ -41,17 +46,23 @@ Authentication and Authorization
 Helm Charts
 ***********
 
+.. rst-class:: rst-columns
+
 .. toctree::
    :maxdepth: 1
    :glob:
 
    /GenAIInfra/helm-charts/README
    /GenAIInfra/helm-charts/*
+   /GenAIInfra/helm-charts/common/*
+   /GenAIInfra/helm-charts/common/**/*
    /GenAIInfra/helm-charts/**/*
 
 Kubernetes Addons
 *****************
 
+.. rst-class:: rst-columns
+
 .. toctree::
    :maxdepth: 1
    :glob:
@@ -63,6 +74,8 @@ Kubernetes Addons
 Microservices Connector
 ***********************
 
+.. rst-class:: rst-columns
+
 .. toctree::
    :maxdepth: 1
    :glob:
@@ -74,6 +87,8 @@ Microservices Connector
 Pipeline Proxy
 **************
 
+.. rst-class:: rst-columns
+
 .. toctree::
    :maxdepth: 1
    :glob:
@@ -85,6 +100,8 @@ Pipeline Proxy
 Scripts
 *******
 
+.. rst-class:: rst-columns
+
 .. toctree::
    :maxdepth: 1
    :glob:

developer-guides/doc_guidelines.rst

@@ -88,7 +88,11 @@ 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.
+as not included in a toctree directive. ReST documents that are intentionally
+left out of the toctree can be tagged with a ``:orphan:`` roll at the top of the
+file (sometimes done on README.rst files we don't need in the generated HTML.
+
+See :ref:`docbuild-troubleshooting` for more information.
 
 Headings
 ********
@@ -711,7 +715,7 @@ markdown content by using an ``include`` directive.
       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 in a toctree directive, it's best to us a .txt extension for
       included files::
 
          .. include:: mdtable.txt

developer-guides/docbuild.rst

@@ -296,6 +296,37 @@ If things look good, you'd proceed to using git (``git add .``) to add and commi
 repo (``git push origin <branchname>``) and submit a PR using the GitHub web
 interface.
 
+.. _docbuild-troubleshooting:
+
+Doc Build Troubleshooting
+*************************
+
+It's worth mentioning again, all ``.md`` and ``.rst`` documents must appear in
+the toctree hierarchy. When a new document is added it might cause the doc build to fail
+because that new document is not found in any of the toctree directives. Some
+doc additions are automatically incorporated through the use of the ``:glob:``
+pattern that pick up file names that match the pattern. Some toctree directives
+use an explicit list of documents that must be updated if a new document is
+added. The ``index.rst`` file in the directory where the new document was added
+(or in parent directory) would be the first place to check if the doc build
+complains that a document is not listed in a toctree.
+
+The :ref:`GenAIExamples` and :ref:`GenAIMicroservices` documents hierarchy are a
+special case.  Both of these documents are augmented at build time by a script
+(:docs_blob:`scripts/maketoc.sh`) that creates headings and toctree references
+(using ``:glob:``) to pick up all documents found in the ``GenAIExamples`` and
+``GenAIComps/comps`` directories.  As new examples or microservice components are
+added, the doc build scripts should automatically incorporate those new
+documents.
+
+Sphinx (and the Myst parser extension) may warn about issues with markdown
+syntax or structure.  Some of these warnings, though reported as errors, are not
+fatal for the doc build.  It's best to address these warnings and errors in the
+offending source file and build the docs again.  (This might mean making changes
+to documents in other OPEA project repos, submitting a PR, and getting that
+approved and merged.)
+
+
 Publish Content
 ***************
 

developer-guides/index.rst

@@ -17,6 +17,7 @@ Documentation Guides
 ********************
 
 .. toctree::
+   :maxdepth: 1
 
    doc_guidelines
    graphviz