dotnet / dotnet/api-docs-sync

Docs Porting Tool improvement

Open
#104 2 comments 0 reactions 0 assignees View on GitHub
epic
Dominant language
C#
Stars
14
Forks
21
PR merge metrics
No merged PRs in 30d

Description

There are several improvements we need to address to stabilize this tool for usage in all dotnet repos in an automated fashion.

## P0

Before tackling anything else, we need to solve the following:

- [x] Separate the two directions into two separate processes. This will help ensure we keep concerns separate and simplify maintenance and future improvements.
- [ ] Add classes that wrap the dotnet-api-docs xml types and members, but only return xml objects. This will simplify working with Roslyn APIs.
- [ ] Use the code in this branch as insipration: https://github.com/dotnet/api-docs-sync/pull/99 so that the Roslyn code consumes the new xml-returning classes.
- [ ] Understand and fix the issue causing the tool to not be able to load Roslyn projects every time we bump dependencies. Use the code in this branch as inspiration: https://github.com/dotnet/api-docs-sync/pull/97

## P1

Only tackle this after we fix the P0s:

- [x] ToDocs: tests into actual unit tests, instead of feature tests. First PR addressing this: https://github.com/dotnet/api-docs-sync/pull/110
- [ ] ToTripleSlash: move _all_ remarks to their own xml files next to the source code, and point to the file in the triple slash xml `` item.
- [ ] Convert the dotnet-api-docs markdown to normal xml if possible.
- [ ] ToTripleSlash: Figure out how to detect examples in remarks efficiently, move them to their own xml files next to the source code, and point to the file in the triple slash `` item.
- [ ] Detect multi-platform documents (*.Unix.cs, *.Windows.cs, etc.) and move their documentation to a single xml file next to the source code, then point to that file in all the triple slash xml items.
- [ ] ToDocs: Port the `-or-` lines in exceptions correctly, to ensure they have enough endlines so they render correctly in MS Docs.
- [ ] ToTripleSlash: backport `-or-` lines in exceptions with `
` or other features to ensure they get wrapped and save space.
- [ ] ToTripleSlash: Add the ability to wrap lines to 120 characters (or a custom number), as requested by WinForms.

## P2

- [ ] Save logs to file. There used to be a change that used System.Threading.Channels, but it was causing some messages to get lost, or not print well so it was backed-out. We can reuse its code but fix the issues: https://github.com/dotnet/api-docs-sync/pull/75
- [x] ~Move the code from this tool into a forked arcade repo and adapt the two executables to be consumable by arcade.~ We already moved this tool to its own repo under dotnet.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.