Documentation generation lifecycle

Documentation generation lifecycle

A documentation generation run is the background work that creates documentation for a project. Use this page to find a run, follow its stages, and choose the next action from its status.

Before you start

A project context identifies which generation runs you are reviewing. The project jobs page takes the project identifier in its route, while manual insights on Operations use the projects returned for your organisation.

Prerequisites

• Know the project whose generation activity you need to inspect.
• Have access to the project jobs route or the Operations page.
• For manual insights, have at least one project returned by the project list.

Find a generation run

A generation run appears either in one project's job history or in the organisation-wide Operations view.

Prerequisites

• Have the project identifier when opening a project-specific list.

Steps

1. Open the route that matches the work you need to review.

   If you need to…	Open

| Review one project's generation runs | Job history | | Review organisation-wide generation activity | Operations overview |

2. On the project jobs page, use the link back to the project when you need the project's main page.

Result: The selected project jobs list or the organisation-wide operations view is on screen.

Understand the lifecycle and screen

The jobs screen is a list of generation runs with loading, empty, active, completed, and failed states. An active run reports progress; an expanded completed or failed row provides more detail.

The page requests up to 50 runs for the selected project and listens for progress, completion, failure, cancellation, and screenshot-progress updates for active runs.

The five displayed stages are shown in this order:

mermaid
flowchart LR
  A[Cloning Repository] --> B[Analyzing Code]
  B --> C[Generating Docs]
  C --> D[Uploading to Database]
  D --> E[Publishing Documents]

The jobs page and Operations page do not ask you to enter values. The Operations page can show a project selector when more than one project is returned; each option uses the returned project name.

Monitor and manage a run

Use this procedure while a run is listed and you need current progress or need to stop an active run.

Prerequisites

• Have the project jobs list open.
• For cancellation, the run has status Running or Pending and Cancel is available.

Steps

1. On the project jobs page, select Refresh, or in Recent Jobs, select Refresh job history.

2. If the active job shows Cancel, select Cancel.

3. Select Are you sure? to confirm the cancellation.

Result: The list is refreshed, or the active run is cancelled and its status changes to Cancelled.

Handle status branches

A job status tells you which part of the generation work is available for review and which controls you can use next.

Prerequisites

• Have the project jobs list open.
• Know the status shown on the job row.

Steps

1. Select a job row with status Completed or Failed to expand its details.

2. Review the expanded result for a completed run or the failure details for a failed run.

3. Use the status-specific control shown on the row.

   Status and condition	Control and outcome
   Completed, Failed, or Cancelled, with created documents	Select Delete Docs once to arm deletion, then select Confirm Delete?.
   Completed, Failed, or Cancelled, with no created documents	Select Delete Job once to arm deletion, then select Confirm Delete?.
   Running or Pending	Monitor the progress display or use Cancel.

Completed and failed rows also support regeneration after review. Continue with run-documentation-work for the generation task.

Result: The selected row is expanded for review, remains active for monitoring, or shows its status-specific action state.

When the run goes wrong

Use the message on screen to decide whether to wait for loading, refresh the relevant surface, or inspect the failed job's details.

Prerequisites

• Have the message on screen.
• For a job message, have the project jobs list open.
• For an Operations message, have access to Operations.

Steps

1. Follow the alternative that matches the message.

   If you see…	Do this
   Jobs failed to load.	Select Refresh on the project jobs page.
   Operations failed to load.	Reopen Operations.
   Loading insights…	Wait for the manual insights panels to load.
   Insights failed to load.	Reopen Operations.
   Job Failed	Select the failed job row and read its error detail.
   A failed job's error detail	Use the displayed error text when following up.

2. If Loading operations…, Loading runs…, Starting..., or Waiting to start... appears, wait for the current loading or job state to update.

Result: You have refreshed the project jobs page, reopened Operations, waited for the current state to update, or read the failed job's error detail and know the next action.

Know what happens next

After you review the run, continue with the page that owns the next task or reference.

The empty jobs state points to Configure & run documentation generation →. After a run completes or fails, the jobs list refreshes so the updated status and run details appear in the list.