Docs Porting Tool improvement
- 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.