Skip to content

data-flows.md

Latest commit

 

History

History
155 lines (125 loc) · 7.18 KB

data-flows.md

File metadata and controls

155 lines (125 loc) · 7.18 KB
Raw

Data flows

Purpose

This page shows which component writes and which reads each file of the source-code pipeline, following living-doc-utilities' Pipeline rules. It names those rules and links them, and defines none.

Read before: Architecture · Next: Contracts

Contents

Flow

collector-gh reads the repositories checked out earlier in the job; each later step reads the files an earlier one wrote. The header and scenario formats are in Authoring formats. Planned sources and outputs are not drawn (Planned).

flowchart LR
    subgraph Sources
        H[(User Story and Functionality<br/>headers in .feature files)]
        P[(Feature headers<br/>in PageObjects)]
        S[(UI test scenarios<br/>in .feature files)]
    end

    subgraph CGH [collector-gh]
        DS[doc-source mode]
        UT[ui-tests mode]
    end

    subgraph TK [toolkit]
        ND[normalize-docs]
        NT[normalize-tests]
        CM[coverage-matrix]
    end

    subgraph GM [generator-markdown]
        TP[technical-project]
        TC[ui-test-catalog]
        CV[coverage-matrix]
    end

    H --> DS
    P --> DS
    S --> UT
    DS --> DSJ[/doc-source.json/]
    UT --> UTJ[/ui-tests.json/]
    DSJ --> ND --> GRJ[/generator-ready.json/] --> TP
    UTJ --> NT --> TCJ[/ui-test-catalog.json/] --> TC
    DSJ --> CM
    UTJ --> CM --> CMJ[/coverage-matrix.json/] --> CV
Loading

Files

Default paths are relative to the step's working directory. Where each step takes its path: collector-gh output layout, toolkit inputs, generator-markdown files.

File Default path Written by Read by
doc-source.json output/collector-gh/doc-source/doc-source.json collector-gh, mode doc-source toolkit normalize-docs and coverage-matrix
ui-tests.json output/collector-gh/ui-tests/ui-tests.json collector-gh, mode ui-tests toolkit normalize-tests and coverage-matrix
generator-ready.json none: the toolkit step's output names it toolkit normalize-docs generator-markdown, document type technical-project
ui-test-catalog.json none: the toolkit step's output names it toolkit normalize-tests generator-markdown, document type ui-test-catalog
coverage-matrix.json none: the toolkit step's output names it toolkit coverage-matrix generator-markdown, document type coverage-matrix
<document-type>.md and <document-type>.run-report.json output/generator-markdown/ generator-markdown people: commit or publish the document

Commands

The three toolkit commands, one step each, and the document type each one's file feeds (toolkit commands):

Command Reads Writes Feeds document-type
normalize-docs doc-source.json generator-ready.json technical-project
normalize-tests ui-tests.json ui-test-catalog.json ui-test-catalog
coverage-matrix doc-source.json and ui-tests.json coverage-matrix.json coverage-matrix

What each document shows: Living Documentation Document Types.

Views

  • The view is chosen at the toolkit step: normalize-docs and coverage-matrix take view, inner (the default) or release (toolkit inputs).
  • normalize-tests takes none: a test catalog has no field that differs by view (normalize-tests).
  • The file records its view in document.view; generator-markdown renders that view and has no view input.
  • What each view shows and drops: Rendering rules — Views.

Pipeline rules

Three of living-doc-utilities' pipeline rules shape this flow. This page names them; each link defines one.

Example

One job's steps: collect a repository's User Stories, normalize them in the release view, render the technical project. Each action is pinned by its release tag, and one project-id names the project.

- uses: actions/checkout@v7
- uses: actions/setup-python@v7
  with: { python-version: '3.14' }
- uses: AbsaOSS/living-doc-collector-gh@v0.2.0
  with:
    project-id: your-project
    doc-source: true
    doc-source-repositories: |
      [{"organization-name": "your-org", "repository-name": "your-repo",
        "us-paths": ["${{ github.workspace }}/features"]}]
- uses: AbsaOSS/living-doc-toolkit@v0.1.0
  with:
    command: normalize-docs
    input: output/collector-gh/doc-source/doc-source.json
    output: output/toolkit/generator-ready.json
    view: release
- uses: AbsaOSS/living-doc-generator-markdown@v0.1.0
  with:
    document-type: technical-project
    source-path: output/toolkit/generator-ready.json

The document lands in output/generator-markdown/technical-project.md. func-paths and pages-paths in the same entry add the Functionalities and Features (repository entry). Every input of each step: collector-gh, toolkit, generator-markdown.

Planned

  • GitHub issues (planned): collector-gh's doc-issues mode, writing doc-entities.json (Documentation Issues).
  • Azure DevOps work items (planned): living-doc-collector-ad, writing doc-entities.json (collector-ad).
  • PDF (planned): living-doc-generator-pdf, rendering the same three toolkit files (generator-pdf).