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>
This commit is contained in:
parent
f669e156d4
commit
dd7532dcf9
3 changed files with 202 additions and 0 deletions
141
doc/_extensions/zephyr/manifest_projects_table.py
Normal file
141
doc/_extensions/zephyr/manifest_projects_table.py
Normal file
|
@ -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,
|
||||
}
|
|
@ -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/**/*",
|
||||
|
|
58
doc/develop/manifest/index.rst
Normal file
58
doc/develop/manifest/index.rst
Normal file
|
@ -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
|
Loading…
Add table
Add a link
Reference in a new issue