🎯 feat: draft generate markdown method.

Author: korawica

src/ddeutil/workflow/cli.py

@@ -57,14 +57,18 @@ def init() -> None:
         wf-example:
           type: Workflow
           desc: |
-            An example workflow template.
+            An example workflow template that provide the demo of workflow.
           params:
             name:
                 type: str
                 default: "World"
           jobs:
             first-job:
               stages:
+
+                - name: "Hello Stage"
+                  echo: "Start say hi to the console"
+
                 - name: "Call tasks"
                   uses: tasks/say-hello-func@example
                   with:
@@ -232,7 +236,7 @@ def workflow_json_schema(
     json_schema = TypeAdapter(template).json_schema(by_alias=True)
     template_schema: dict[str, str] = {
         "$schema": "http://json-schema.org/draft-07/schema#",
-        "title": "Workflow Configuration Schema",
+        "title": "Workflow Configuration JSON Schema",
         "version": __version__,
     }
     with open(output, mode="w", encoding="utf-8") as f:

src/ddeutil/workflow/workflow.py

@@ -284,6 +284,46 @@ def __validate_jobs_need__(self) -> Self:
 
         return self
 
+    def md(self) -> str:  # pragma: no cov
+        """Generate the markdown template."""
+
+        def align_newline(value: str) -> str:
+            return value.rstrip("\n").replace("\n", "\n                ")
+
+        info: str = (
+            f"| Author: nobody "
+            f"| created_at: `{self.created_at:%Y-%m-%d %H:%M:%S}` "
+            f"| updated_at: `{self.updated_dt:%Y-%m-%d %H:%M:%S}` |\n"
+            f"| --- | --- | --- |"
+        )
+        jobs: str = ""
+        for job in self.jobs:
+            job_model: Job = self.jobs[job]
+            jobs += f"### {job}\n{job_model.desc or ''}\n"
+            stags: str = ""
+            for stage_model in job_model.stages:
+                stags += (
+                    f"#### {stage_model.name}\n\n"
+                    f"Stage ID: {stage_model.id or ''}\n"
+                    f"Stage Model: {stage_model.__class__.__name__}\n\n"
+                )
+            jobs += f"{stags}\n"
+        return dedent(
+            f"""
+                # Workflow: {self.name}\n
+                {align_newline(info)}\n
+                {align_newline(self.desc)}\n
+                ## Parameters\n
+                | name | type | default | description |
+                | --- | --- | --- | : --- : |
+
+                ## Jobs\n
+                {align_newline(jobs)}
+                """.lstrip(
+                "\n"
+            )
+        )
+
     def job(self, name: str) -> Job:
         """Return the workflow's Job model that getting by an input job's name
         or job's ID. This method will pass an extra parameter from this model

tests/test_workflow.py

@@ -425,3 +425,14 @@ def test_workflow_parameterize(test_path):
         # NOTE: Raise if passing parameter that does not set on the workflow.
         with pytest.raises(WorkflowError):
             workflow.parameterize({"foo": "bar"})
+
+
+def test_workflow_markdown(test_path):
+    workflow = Workflow.from_conf(
+        "stream-workflow", path=test_path / "conf/example"
+    )
+    md_file: Path = test_path / "stream-workflow.md"
+    with md_file.open(mode="w") as f:
+        f.write(workflow.md())
+
+    md_file.unlink(missing_ok=True)