feat(web)

- add help pages
- refactor page footer generation
- expand custom colors

Author: tcjennings

packages/cm-web/src/lsst/cmservice/web/pages/__init__.py

@@ -20,6 +20,7 @@
 from .campaign_edit import CampaignClonePage, CampaignEditPage
 from .campaign_overview import CampaignOverviewPage
 from .canvas import CanvasScratchPage
+from .help import HelpPage
 from .node_detail import NodeDetailPage
 
 
@@ -32,6 +33,16 @@ async def campaign_overview_page(
         await page.render()
 
 
+@ui.page("/help", response_timeout=settings.timeout)
+@ui.page("/help/{_:path}", response_timeout=settings.timeout)
+async def cm_help_page(
+    client_: Annotated[AsyncClient, Depends(CLIENT_FACTORY.get_aclient)],
+) -> None:
+    await ui.context.client.connected()
+    if page := await HelpPage(title="CM Service Help").setup(client_):
+        await page.render()
+
+
 @ui.page("/campaign/{campaign_id}", response_timeout=settings.timeout)
 async def campaign_detail_page(
     campaign_id: str, client_: Annotated[AsyncClient, Depends(CLIENT_FACTORY.get_aclient)]

packages/cm-web/src/lsst/cmservice/web/pages/campaign_detail.py

@@ -187,6 +187,9 @@ def drawer_contents(self) -> None:
                 {"cards": "Cards", "table": "Table"}, value="cards", on_change=self.handle_node_display_toggle
             ).classes("flex-1").bind_value(self, "nodes_view", strict=False)
 
+    async def footer_contents(self) -> None:
+        ui.label().classes("text-xs").bind_text_from(self, "campaign_id", strict=False)
+
     async def setup(self, client_: AsyncClient | None = None, *, campaign_id: str = "") -> Self:
         """Async method called at page creation. Subpages can override this
         method to perform data loading/prep, etc., before calling render().
@@ -260,9 +263,6 @@ async def create_content(self) -> None:
                 ui.fab_action("ios_share", label="export", on_click=export_navigator).disable()
                 ui.fab_action("copy_all", label="clone", on_click=clone_navigator)
 
-        with self.footer:
-            ui.label().classes("text-xs").bind_text_from(self, "campaign_id", strict=False)
-
         self.hide_spinner()
 
     @ui.refreshable_method

packages/cm-web/src/lsst/cmservice/web/pages/campaign_edit.py

@@ -130,15 +130,15 @@ async def create_content(self) -> None:
             });
         """)
 
-        with self.footer:
-            ui.label().classes("text-xs").bind_text_from(self, "campaign_id", strict=False)
-
     def drawer_contents(self) -> None:
         """Right-side menu drawer contents rendered in a ui.column."""
         ui.button("Save", icon="save", on_click=self.handle_upload).classes("w-50")
         ui.button("Export", icon="save_alt", on_click=self.handle_export).classes("w-50")
         ui.button("Import", icon="file_upload").classes("w-50").disable()
 
+    async def footer_contents(self) -> None:
+        ui.label().classes("text-xs").bind_text_from(self, "campaign_id", strict=False)
+
     async def handle_node_edit(self, data: GenericEventArguments) -> None:
         """Callback target for "edit" events emitted by nodes on the canvas."""
         step_id, step_name = data.args

packages/cm-web/src/lsst/cmservice/web/pages/common.py

@@ -65,6 +65,21 @@ def apply_style() -> None:
             white=Palette.WHITE.light,
             dark=Palette.BLACK.light,
             dark_page=Palette.BLACK.dark,
+            # Custom, Alt, and Deep Colors
+            red=Palette.RED.light,
+            deepred=Palette.RED.dark,
+            orange=Palette.ORANGE.light,
+            deeporange=Palette.ORANGE.dark,
+            yellow=Palette.YELLOW.light,
+            deepyellow=Palette.YELLOW.dark,
+            green=Palette.GREEN.light,
+            deepgreen=Palette.GREEN.dark,
+            blue=Palette.BLUE.light,
+            deepblue=Palette.BLUE.dark,
+            indigo=Palette.INDIGO.light,
+            deepindigo=Palette.INDIGO.dark,
+            violet=Palette.VIOLET.light,
+            deepviolet=Palette.VIOLET.dark,
             # Custom Colors for Statuses
             **{status.name: status.hex for status in StatusDecorators},
         )
@@ -82,6 +97,10 @@ def create_header(self) -> None:
         ui.space()
         ui.button(icon="menu", on_click=lambda: self.toggle_drawer()).props("flat color=white")
 
+    async def footer_contents(self) -> None:
+        """Hook method for subclasses to implement their own footer objects"""
+        pass
+
     def page_layout(self) -> None:
         self.create_drawer()
         with ui.header(elevated=True).classes(
@@ -96,11 +115,9 @@ def page_layout(self) -> None:
         ) as self.content:
             pass
 
-        with ui.footer(bordered=False, elevated=True).classes(
+        self.footer = ui.footer(bordered=False, elevated=True).classes(
             "h-[2rem] min-h-[2rem] items-center justify-between px-4 p-0"
-        ) as self.footer:
-            for footer in self.footers:
-                ui.label(footer).classes("text-xs m-0")
+        )
 
         self.overlay_div = ui.element("div").classes("hidden")
 
@@ -117,6 +134,17 @@ async def render(self) -> None:
         Subclasses should use the `create_content()` method, which is called
         from within the content column's context manager.
         """
+        with self.footer:
+            with ui.row().classes("items-center gap-2"):
+                for footer in self.footers:
+                    ui.label(footer).classes("text-xs m-0")
+                await self.footer_contents()
+
+            with ui.row().classes("items-center gap-2"):
+                ui.button(icon="help_outline", on_click=lambda: ui.navigate.to("/help")).classes(
+                    "text-white bg-info m-0"
+                ).props("flat round size=sm")
+
         with self.content:
             await self.create_content()
 

packages/cm-web/src/lsst/cmservice/web/pages/help.py

@@ -0,0 +1,138 @@
+from nicegui import ui
+
+from ..settings import settings
+from .common import CMPage
+
+
+class HelpPage(CMPage):
+    """A page for general help and documentation. Each section is rendered
+    as a subpage. Any nested help route not associated with a specific subpage
+    is served by the main help landing page instead of producing a 404 error.
+    """
+
+    def drawer_contents(self) -> None: ...
+
+    async def create_content(self) -> None:
+        with ui.button_group().classes("w-full h-[4rem]"):
+            ui.button("Help", on_click=lambda: ui.navigate.to("/help"), color="secondary").classes("flex-1")
+            ui.button("Step", on_click=lambda: ui.navigate.to("/help/step"), color="secondary").classes(
+                "flex-1"
+            )
+            ui.button("BPS", on_click=lambda: ui.navigate.to("/help/bps"), color="secondary").classes(
+                "flex-1"
+            )
+            ui.button("Butler", on_click=lambda: ui.navigate.to("/help/butler"), color="secondary").classes(
+                "flex-1"
+            )
+            ui.button("LSST", on_click=lambda: ui.navigate.to("/help/lsst"), color="secondary").classes(
+                "flex-1"
+            )
+            ui.button("WMS", on_click=lambda: ui.navigate.to("/help/wms"), color="secondary").classes(
+                "flex-1"
+            )
+            ui.button("Site", on_click=lambda: ui.navigate.to("/help/site"), color="secondary").classes(
+                "flex-1"
+            )
+
+        with ui.element("div").classes("w-full h-full overflow-x-hidden overflow-y-auto"):
+            ui.sub_pages(
+                {
+                    "/help": self.landing_help,
+                    "/help/step": self.step_help,
+                    "/help/bps": self.bps_help,
+                    "/help/butler": self.butler_help,
+                    "/help/lsst": self.lsst_help,
+                    "/help/wms": self.wms_help,
+                    "/help/site": self.site_help,
+                },
+                show_404=False,
+            ).classes("w-full h-full")
+
+    async def landing_help(self) -> None:
+        """The main landing page for the help page network. Served by the
+        `/help` route and any `/help/*` route not otherwise associated with a
+        subpage.
+        """
+        ui.markdown("""
+        # Main Help
+        Choose a help section from the options above.
+        """)
+
+        with ui.expansion(
+            text="Glossary", caption="A brief glossary of terms used throughout CM Service."
+        ).classes("w-full"):
+            with (
+                ui.element("div")
+                .classes("w-full overflow-x-auto")
+                .style("column-count: 2; column-gap: 2rem;")
+            ):
+                await self.markdown_help_section("cmglossary.md")
+
+        with ui.expansion(
+            text="Page Overview", caption="An overview of Pages available in CM Service."
+        ).classes("w-full"):
+            with (
+                ui.element("div")
+                .classes("w-full overflow-x-auto")
+                .style("column-count: 2; column-gap: 2rem;")
+            ):
+                await self.markdown_help_section("cmpages.md")
+
+    async def bps_help(self) -> None:
+        ui.markdown("""
+        # BPS Help
+        """)
+
+        await self.manifest_spec_iframe("bps")
+
+    async def step_help(self) -> None:
+        ui.markdown("""
+        # Step Help
+        """)
+
+        await self.manifest_spec_iframe("step")
+
+    async def butler_help(self) -> None:
+        ui.markdown("""
+        # Butler Help
+        """)
+
+        await self.manifest_spec_iframe("butler")
+
+    async def lsst_help(self) -> None:
+        ui.markdown("""
+        # LSST Help
+        """)
+
+        await self.manifest_spec_iframe("lsst")
+
+    async def wms_help(self) -> None:
+        ui.markdown("""
+        # WMS Help
+        """)
+
+        await self.manifest_spec_iframe("wms")
+
+    async def site_help(self) -> None:
+        ui.markdown("""
+        # Site Help
+        """)
+
+        await self.manifest_spec_iframe("site")
+
+    async def manifest_spec_iframe(self, kind: str) -> None:
+        """Adds an iframe element into which is loaded the Manifest Spec html
+        reference page. This page is generated from pydantic models as
+        jsonschema then HTML is generated from that.
+        """
+        ui.element("iframe").props(f"src='/static/docs/{kind}_spec.html'").classes("w-full h-full")
+
+    async def markdown_help_section(self, md: str) -> None:
+        """Adds a markdown element with the contents of the markdown file
+        referenced by the `md` argument. This file must exist in the "markdown"
+        directory relative to the static content location indicated by the
+        `settings.static_dir` Path.
+        """
+
+        markdown_content = (settings.static_dir / "markdown" / md).read_text()
+        ui.markdown(markdown_content, sanitize=True).classes("w-full h-full")

packages/cm-web/src/lsst/cmservice/web/pages/node_detail.py

@@ -44,6 +44,9 @@ class NodeDetailPage(CMPage[NodeDetailPageModel]):
 
     def drawer_contents(self) -> None: ...
 
+    async def footer_contents(self) -> None:
+        ui.label().classes("text-xs").bind_text_from(self, "node_id", strict=False)
+
     async def setup(self, client_: AsyncClient | None = None, *, node_id: str = "") -> Self:
         """Data intensive setup method that fetches the full node description
         from CM API. Run at page setup to populate the page `model` with the
@@ -62,9 +65,6 @@ async def setup(self, client_: AsyncClient | None = None, *, node_id: str = "")
             "logs": data["logs"],
         }
 
-        with self.footer:
-            ui.label().classes("text-xs").bind_text_from(self, "node_id", strict=False)
-
         self.breadcrumbs.append(data["node"]["name"])
         self.create_header.refresh()
         return self

packages/cm-web/src/lsst/cmservice/web/static/markdown/cmglossary.md

@@ -0,0 +1,17 @@
+- `campaign`: A complete end-to-end data processing workflow.
+- `manifest`: A kind-specific configuration document that defines the parameters available to a campaign node, step, or group.
+Each kind of manifest supports difference configuration parameters and controls the generation of artifacts used by BPS and other launchers. A manifest may be configured at the group, step, campaign, or library level. See `configuration chain`.
+- `library`: A generic, "global" manifest of a particular kind used as a fallback of last resort in a configuration chain.
+A Library manifest is always "version 0" and are read-only.
+- `graph`
+- `node`: A Node is a single atomic unit in a campaign graph.
+A Node is usually a step or a group, but can also be a breakpoint or start/end marker.
+Additional types of nodes may be introduced to CM Service to perform more specific operations as a campaign progresses.
+- `step`: A Step is a graph node that specifically represents a unit of LSST Pipeline work -- which could be a pipeline task, step, or stage -- any unit of pipeline work representable by a single "Pipeline YAML" declaration can be a `step`.
+- `group`: Every `step` in a campaign graph is broken out into one or more `group`s.
+A group inherits all its configuration from the step that generated it, including the "Pipeline YAML" declaration, and differs only in the Butler data query that constrains the data IDs used by the group.
+Groups are the unit of parallelization for executing campaign graphs.
+- `collect`: Since every `step` "fans out" into one or more `groups`, the `collect` Node is the "fan in" operation that builds Butler collections that gather together all the output run collections of its ancestor groups. A `collect` node also serves as a checkpoint in the campaign graph, since every ancestor group must be completed before the `collect` node can start.
+- `configuration chain`: Every group's configuration is generated by a "chain" of manifests. For every configuration parameter a group uses from a manifest, each manifest in the "chain" is checked until the parameter is found. The ordering of this "chain" is from most specific to most general: group -> step -> campaign -> library.
+- `launcher`: A launcher is the mechanism CM Service uses to perform work. For example, to run a "bps submit" command for a group, CM Service first writes a BASH script artifact that calls "bps submit" and then uses a `launcher` to run that script. A common launcher is the HTCondor launcher, which submits the script as a job to an HTCondor Schedd host in the local universe.
+- `version`: Many objects in CM Service are versioned, especially manifests and nodes. Versions provide a history and provenance for tracking changes made to a campaign's elements. CM Service does not support branching versions, so the latest version of any object is always the newest, but nodes track in their metadata which version of a manifest was used to produce the node's configuration.

packages/cm-web/src/lsst/cmservice/web/static/markdown/cmpages.md

@@ -0,0 +1,14 @@
+- Every page in CM Service has a header, a side panel menu, and a footer.
+Each page may display different information in these sections, but a "help" button is always present in the footer, and will bring you back to this help section.
+Similarly, every page header has a "Campaign Management" label that is a link back to the Campaign Overview page.
+
+- *Campaign Overview*. The main home page of CM Service.
+This page shows a card for each campaign known to CM Service.
+On each card is an Avatar, the campaign name and status, a histogram of node-statuses, and a pause/resume switch.
+Additional buttons allow you to "favorite" or "hide" a campaign.
+You may also "clone" a campaign to make a copy of its graph and configuration, or "export" the campaign for offline use.
+
+- *Campaign Detail*. Each card on the *campaign overview* page is linked to a *Campaign Detail* page for that campaign.
+On this detail page, you can access a Mermaid rendering of the campaign graph, review gauges that display the campaign progress, review and edit any Campaign Manifests, and review and edit any Nodes in the campaign.
+The collection of campaign nodes is displayed as a set of Node Detail cards or a simplified Table, with a switch between the two views available in the side panel menu.
+Node Detail cards have richer content but are consequently more visually complex; the table view is simpler but has a restricted set of available operations.