doc: add manifest extension

Generate index of west projects and information about them.
Based on an extension from sdk-nrf repo.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>

doc/_extensions/zephyr/manifest_projects_table.py

@@ -0,0 +1,141 @@
+"""
+Manifest Revisions Table
+========================
+
+This extension allows to render a table containing the revisions of the projects
+present in a manifest file.
+
+Usage
+*****
+
+This extension introduces a new directive: ``manifest-projects-table``. It can
+be used in the code as::
+
+    .. manifest-projects-table::
+        :filter: active
+
+where the ``:filter:`` option can have the following values: active, inactive, all.
+
+Options
+*******
+
+- ``manifest_projects_table_manifest``: Path to the manifest file.
+
+Copyright (c) Nordic Semiconductor ASA 2022
+Copyright (c) Intel Corp 2023
+SPDX-License-Identifier: Apache-2.0
+"""
+
+import re
+from typing import Any, Dict, List
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+from west.manifest import Manifest
+
+
+__version__ = "0.1.0"
+
+
+class ManifestProjectsTable(SphinxDirective):
+    """Manifest revisions table."""
+
+    option_spec = {
+        "filter": directives.unchanged,
+    }
+
+    @staticmethod
+    def rev_url(base_url: str, rev: str) -> str:
+        """Return URL for a revision.
+
+        Notes:
+            Revision format is assumed to be a git hash or a tag. URL is
+            formatted assuming a GitHub base URL.
+
+        Args:
+            base_url: Base URL of the repository.
+            rev: Revision.
+
+        Returns:
+            URL for the revision.
+        """
+
+        if re.match(r"^[0-9a-f]{40}$", rev):
+            return f"{base_url}/commit/{rev}"
+
+        return f"{base_url}/releases/tag/{rev}"
+
+    def run(self) -> List[nodes.Element]:
+        active_filter = self.options.get("filter", None)
+
+        manifest = Manifest.from_file(self.env.config.manifest_projects_table_manifest)
+        projects = []
+        for project in manifest.projects:
+            if project.name == "manifest":
+                continue
+            if active_filter == 'active' and manifest.is_active(project):
+                projects.append(project)
+            elif active_filter == 'inactive' and not manifest.is_active(project):
+                projects.append(project)
+            elif active_filter == 'all' or active_filter is None:
+                projects.append(project)
+
+        # build table
+        table = nodes.table()
+
+        tgroup = nodes.tgroup(cols=2)
+        tgroup += nodes.colspec(colwidth=1)
+        tgroup += nodes.colspec(colwidth=1)
+        table += tgroup
+
+        thead = nodes.thead()
+        tgroup += thead
+
+        row = nodes.row()
+        thead.append(row)
+
+        entry = nodes.entry()
+        entry += nodes.paragraph(text="Project")
+        row += entry
+        entry = nodes.entry()
+        entry += nodes.paragraph(text="Revision")
+        row += entry
+
+        rows = []
+        for project in projects:
+            row = nodes.row()
+            rows.append(row)
+
+            entry = nodes.entry()
+            entry += nodes.paragraph(text=project.name)
+            row += entry
+            entry = nodes.entry()
+            par = nodes.paragraph()
+            par += nodes.reference(
+                project.revision,
+                project.revision,
+                internal=False,
+                refuri=ManifestProjectsTable.rev_url(project.url, project.revision),
+            )
+            entry += par
+            row += entry
+
+        tbody = nodes.tbody()
+        tbody.extend(rows)
+        tgroup += tbody
+
+        return [table]
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    app.add_config_value("manifest_projects_table_manifest", None, "env")
+
+    directives.register_directive("manifest-projects-table", ManifestProjectsTable)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

doc/conf.py

@@ -82,6 +82,7 @@ extensions = [
     "zephyr.warnings_filter",
     "zephyr.doxyrunner",
     "zephyr.vcs_link",
+    "zephyr.manifest_projects_table",
     "notfound.extension",
     "sphinx_copybutton",
     "sphinx_togglebutton",
@@ -171,6 +172,7 @@ html_context = {
         "API": f"{reference_prefix}/doxygen/html/index.html",
         "Kconfig Options": f"{reference_prefix}/kconfig.html",
         "Devicetree Bindings": f"{reference_prefix}/build/dts/api/bindings.html",
+        "West Projects": f"{reference_prefix}/develop/projects/index.html",
     }
 }
 
@@ -292,6 +294,7 @@ external_content_contents = [
 ]
 external_content_keep = [
     "reference/kconfig/*",
+    "develop/manifest/index.rst",
     "build/dts/api/bindings.rst",
     "build/dts/api/bindings/**/*",
     "build/dts/api/compatibles/**/*",

doc/develop/manifest/index.rst

@@ -0,0 +1,58 @@
+:orphan:
+
+.. _west_projects_index:
+
+West Projects index
+###################
+
+See :ref:`external-contributions` for more information about
+this contributing and review process for imported components.
+
+Active Projects/Modules
++++++++++++++++++++++++
+
+The projects below are enabled by default and will be downloaded when you
+call `west update`. Many of the projects or modules listed below are
+essential for building generic Zephyr application and include among others
+hardware support for many of the platforms available in Zephyr.
+
+To disable any of the active modules, for example a specific HAL, use the
+following commands::
+
+        west config manifest.project-filter -- -hal_FOO
+        west update
+
+.. manifest-projects-table::
+   :filter: active
+
+Inactive and Optional Projects/Modules
+++++++++++++++++++++++++++++++++++++++
+
+
+The projects below are optional and will not be downloaded when you
+call `west update`. You can add any of the the projects or modules listed below
+and use them to write application code and extend your workspace with the added
+functionality.
+
+To enable any of the modules below, use the following commands::
+
+        west config manifest.project-filter -- +nanopb
+        west update
+
+.. manifest-projects-table::
+   :filter: inactive
+
+External Projects/Modules
+++++++++++++++++++++++++++
+
+
+The projects listed below are external and are not directly imported into the
+default manifest.
+To use any of the projects below, you will need to define your own manifest
+file which includes them.  See :ref:`west-manifest-import` for information on
+recommended ways to do this while still inheriting the mandatory modules from
+Zephyr's :file:`west.yml`.
+
+.. rst-class:: rst-columns
+
+- TBD