Skip to content

README.md

Latest commit

 

History

History
41 lines (30 loc) · 1.96 KB

README.md

File metadata and controls

41 lines (30 loc) · 1.96 KB

Build API Browser metadata for Steeltoe 2, 3 and 4

Tip

Building the API Browser documentation is not required for the site to run locally.

Generate API Browser documentation and process all markdown with the included PowerShell script build-metadata.ps1:

cd build
pwsh ./build-metadata.ps1

This process can take a while to complete, will display many warnings and may increase build time in subsequent local runs of Steeltoe.io.

Tip

build-metadata.ps1 takes an optional parameter to process one Steeltoe version at a time. For example, running ./build-metadata.ps1 4 will clone and build API Browser metadata for only v4. Or run ./build-metadata.ps1 source to use local Steeltoe sources in a sibling directory.

Passing a version to build-metadata.ps1 is likely to produce failures during docfx build. These failures can be ignored, but will result in 404 errors if you try to view API Browser pages that were not generated on your machine.

What does the script do?

  1. Download docfx binaries (temporary workaround for .NET 10 support)
  2. Clone several copies of Steeltoe (using metadata.conf to identify checkout targets)
  3. Run docfx metadata api-v{version}.json for each copy
    1. This command will produce many yaml files and place them in docs, alongside the index pages for each API version
    2. The script offers a parameter to target a single version (for example: build-metadata.ps1 3)
  4. Run docfx build with docfx-all.json, which will copy the html files into wwwroot of the Steeltoe.io project

Checking external links locally

Check external links in markdown files with the same tools CI uses (no build required):

pwsh build/check-external-links.ps1

Requires lychee. Settings are shared between CI and the local script via lychee.toml at the repo root.