Skip to content

[Code snippet importer] Add tooling to import code snippet files #805

Open

Description

@gewarren

The pipeline that generates the .NET API reference ECMAXML files that live in this repo uses https://github.com/mono/api-doc-tools to reflect over the DLL files and, optionally, imports documentation from matching XML files. When documentation is imported, the compiler-generated XML file can contain code examples that are referenced by a relative path to a C# file in the source repo. Here are two examples, one using XML and one using Markdown:

The problem is that these code files are not captured in the compiler output. When we generate the API files in this docs repo, we need to find such missing code files in the source repo and then copy them here so the references can resolve. Optionally, we should also copy the .csproj file for each file so we can compile the code, but that is secondary. Perhaps we can use the SourceLinkInformation to find the original source file for the API, and from there, use the relative path to find the linked code example file (usually in the 'tests' directory).

This tool could be run as part of the pipeline or as a separate step.

In this commit, you can see that the raw docs copied in by the mdoc pipeline contain links to nonexistent files, and the changes had to be reverted manually.

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions