From d6987b9acd54c8282984b01f9cbcd8236adf8137 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Fri, 27 Sep 2024 11:19:39 -0700 Subject: [PATCH] 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 --- README.md | 53 ----------------------------- README.rst | 10 ++++++ community/charter.md | 2 +- community/index.rst | 4 --- deploy/index.rst | 17 +++++++++ developer-guides/doc_guidelines.rst | 8 +++-- developer-guides/docbuild.rst | 31 +++++++++++++++++ developer-guides/index.rst | 1 + 8 files changed, 66 insertions(+), 60 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index a9285060..00000000 --- a/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# OPEA Project - -**Mission**: Create an open platform project that enables the creation of open, multi-provider, robust, and composable GenAI solutions that harness the best innovation across the ecosystem. - -Here are useful OPEA sites within the Linux Foundation AI & Data Organization: - -* Website: [https://opea.dev](https://opea.dev) -* X/Twitter: [https://twitter.com/opeadev](https://twitter.com/opeadev) -* Linkedin: [https://www.linkedin.com/company/opeadev](https://www.linkedin.com/company/opeadev) -* Github: [https://github.com/opea-project](https://github.com/opea-project) -* Contact us at: [info@opea.dev](mailto:info@opea.dev) - -The OPEA platform includes: - -- Composable building blocks for state-of-the-art generative AI systems - including LLMs, data stores, and prompt engines -- Architectural blueprints of retrieval-augmented generative AI end-to-end workflows -- A four-step assessment for grading generative AI systems around performance, - features, trustworthiness, and enterprise-grade readiness - -Check out the -[LF AI & Data Press Release](https://lfaidata.foundation/blog/2024/04/16/lf-ai-data-foundation-launches-open-platform-for-enterprise-ai-opea-for-groundbreaking-enterprise-ai-collaboration/) and -[Intel's blog post](https://www.intel.com/content/www/us/en/developer/articles/news/introducing-the-open-platform-for-enterprise-ai.html). - -## Technical Steering Committee - -- [Ke Ding](https://www.linkedin.com/in/dingke/), Senior Prinicipal AI Engineer, Intel -- [Malini Bhandaru](https://www.linkedin.com/in/malinibhandaru/), Senior Principal Engineer, Intel (Chair) -- [Amr Abdelhalem](https://www.linkedin.com/in/amrhalem/), SVP, Head of Cloud Platforms, Fidelity -- [Robert Hafner](https://www.linkedin.com/in/roberthafner/), Senior Principal Architect, Comcast -- Steve Grubb, Senior Principal Engineer, Red Hat -- [Nathan Cartwright](https://www.linkedin.com/in/nathan-cartwright-2008228/), Chief Architect - AI, CDW -- [Logan Markewich](https://www.linkedin.com/in/logan-markewich/), Founding Software Developer, LlamaIndex -- [Justin Cormack](https://www.linkedin.com/in/justincormack/), CTO, Docker -- [Melissa Mckay](https://www.linkedin.com/in/melissajmckay/), Head of Developer Relations, JFrog - -## Member companies at launch: - -* Anyscale -* Cloudera -* Datastax -* Domino Data Lab -* Hugging Face -* Intel -* KX -* MariaDB Foundation -* MinIO -* Qdrant -* Red Hat -* SAS -* VMware by Broadcom -* Yellowbrick Data -* Zilliz diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..4a3cecc9 --- /dev/null +++ b/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 diff --git a/community/charter.md b/community/charter.md index e7713e7a..b2a3b380 100644 --- a/community/charter.md +++ b/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 diff --git a/community/index.rst b/community/index.rst index da60a330..32ecd38c 100644 --- a/community/index.rst +++ b/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 ******** diff --git a/deploy/index.rst b/deploy/index.rst index d1edc497..cfdb12c7 100644 --- a/deploy/index.rst +++ b/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` 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: diff --git a/developer-guides/doc_guidelines.rst b/developer-guides/doc_guidelines.rst index 780bbab8..537a881d 100644 --- a/developer-guides/doc_guidelines.rst +++ b/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 diff --git a/developer-guides/docbuild.rst b/developer-guides/docbuild.rst index f93b57f3..2b29e490 100644 --- a/developer-guides/docbuild.rst +++ b/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 ``) 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 *************** diff --git a/developer-guides/index.rst b/developer-guides/index.rst index ab6cdcf7..2b9ee21f 100644 --- a/developer-guides/index.rst +++ b/developer-guides/index.rst @@ -17,6 +17,7 @@ Documentation Guides ******************** .. toctree:: + :maxdepth: 1 doc_guidelines graphviz