dotnet / dotnet/api-docs-sync

Docs Porting Tool improvement

未关闭
#104 2 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
epic
主要语言
C#
星标
14
派生
21
PR 合并指标
30 天内没有已合并 PR

描述

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.

贡献指南

这个仓库没有索引到贡献指南

调研方向

这是一份范围广泛的稳定性路线图,其中没有指定具体的文件或测试。首先选择一个未勾选的 P0 项目,并阅读该项目关联的 pull request,尤其是 PRs 99 或 97;完成情况应通过一个具有明确验证路径的聚焦 issue 或任务来定义。

由索引模型根据 Issue 内容生成。

评估

技术栈
csharp
领域
documentation, tooling
Issue 类型
功能
难度
5/5
预计耗时
一周以上
活跃度
停滞
描述清晰度
需要澄清
新手友好度
20/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。