Pipeline API Documentation

Summary

This repository contains documentation for the 51Degrees Pipeline API.

In addition, it contains information of how to document the API consistently:

• Documenting - Guidance on writing the documentation in this repository.
• Documenting Code - Guidance on documenting code in other repositories in order to automatically generate pages in the same style as the documentation in this repository.

Documentation is written and maintained in Markdown format. A customized build of Doxygen is then used to generate HTML pages from the Markdown source files. Finally, some custom CSS is used to apply 51Degrees branding and styling.

CSS Generation: The custom CSS styling is generated from the 51Degrees Pattern Library. See the pattern library README for instructions on building and updating the CSS files.

Structure

Documentation structure

The final generated documentation can be broken down into three major groups:

• The 'written' pages contain entirely hand-written content. They live in this repository.
• The 'generated' pages contain reference documentation that has been generated automatically from the source code and associated comments. These are built from the sub modules referenced in this repository by the continuous build pipeline when main is updated.
• Example pages contain a combination of hand-written and generated content. The content for the page file itself is maintained in this repository. However, the example code for each language is pulled in from the generated pages. In order to know the name of the example code file, you will need to generate the HTML documentation from the relevant sub-module.

Repository Directory Structure

Source	Description
src/	All documentation source lives in the src directory in markdown form with the addition of DoxyGen syntax.
docs/	HTML documentation generated from src/ ends up here. This is what is displayed on the documentation pages.
Doxyfile	Configuration for generating the documentation using DoxyGen.
DoxygenLayout.xml	Defines how the navigation is layed out in the generated documentation.
examplegrabber.js	Included in the generated documentation to pull in language specific examples.
pattern-library	PatternLab submodule which generates the custom CSS used in the generated documentation.

Building HTML Documents

This is only intended to be performed by 51Degrees employees.

Automatic

The documentation can be generated by using the Build workflow.

It will:

• clone the API repos (since this docs depend on some files from there);
• build this repo's documentation by running Doxygen in the docs directory, which will result in a x.y directory (a documentation version number);
• go through all of the API repos and build their documentation the same way, then copy their resulting x.y directory to x.y/apis/$repo;
• checkout the gh-pages branch and overwrite the x.y directory there with the newly generated one;
• if there are any changes - commit them and push to gh-pages.

A similar workflow is launched for any pull requests, except instead of being pushed to gh-pages the resulting documentation is packed as a CI artifact for local previewing.

Manual

1. Follow pattern-library's README.md to update the CSS files in docs.
2. Run the generation script in the latest dotnet/sdk Docker container (or any other Debian/Ubuntu-based container with PowerShell):

docker run --rm -it --platform linux/amd64 -v .:/src -w /src mcr.microsoft.com/dotnet/sdk:9.0 \
  pwsh ./ci/generate-documentation.ps1