Overview
The LiveDoc feature of the Developer Portal allows you to have a dynamically generated report that summarises your code repository.
We built the LiveDoc service with a C# API backend, hosted as a static web app in Azure, and featuring a Jekyll-based frontend. The LiveDoc feature extracts relevant data from a given repository, including repository stats, contributor information, and product vision, to create a well-organised Markdown file.
Key information extracted for LiveDoc:
- Repository stats: Primary languages used, file count, lines of code, last updated date.
- Overview: Based on the repo’s main README.md file.
- Top contributors: A list of the main contributors to the repository.
- Product canvas files: Extracted if any
canvas/*.mdfiles exist in the repository and if they contain one of the supported canvas types. More info
Workflow stages
Stage 1: Product stakeholder defines product canvas files
- The product stakeholder creates one or more product canvas files outlining the product’s goals, purpose, and strategic direction.
- They save these files as Markdown files (i.e.,
canvas/vision-canvas.md) and uploads the files to their code repository.
Stage 2: Configuration submission
- The product stakeholder provides the following details to generate the LiveDoc:
- Repository URL
- Repository branch
- LiveDoc title
- Author username
- Personal access token (for accessing the repository) More info
Stage 3: Configuration entry in Developer Portal
- An admin user from Developer Portal team receives the configuration details from the product stakeholder and creates a new configuration entry, using the provided details.
- This configuration is stored in Cosmos DB for future use during the LiveDoc report generation process.
- They also store the token identifier in the Developer Portal key vault.
Stage 4: LiveDoc report generation process
- The admin user triggers the LiveDoc report generation process for the specified repository.
- The application performs the following tasks:
- Scans the repository using the provided token (fine-grained token) and retrieves key details such as:
- Repository statistics (e.g., primary languages, file count, lines of code, last updated date).
- Overview section from the repo’s main
README.mdfile. - A list of top contributors to the repository.
- Checks for the presence of the
canvas/*.mdfiles. If found, theProduct canvassection is included in the LiveDoc report. - The LiveDoc report is generated as a Markdown file, containing all the extracted details and formatted accordingly.
- Scans the repository using the provided token (fine-grained token) and retrieves key details such as:
Stage 5: Publishing
- The LiveDoc report is publised to the Developer Portal site, only visible to the internal users.
- The admin user then informs the product stakeholder that the LiveDoc report has been generated and provides them with a link to the report.
Conclusion
This workflow describes the steps involved in generating a LiveDoc report from a project repository through the Developer Portal. The process ensures that the product vision, repository statistics, overview, and contributor information are all accurately captured, maintained, and made available to stakeholders in a well-organised format.