[Docs][CI] Ensure docfx links stay valid, prepare future xml API docs options, keep docs simple maintainable and introduce CI integration for this
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 25/100
- Issue 类型
- 功能
- 描述清晰度
- 需要澄清
- 活跃度
- 停滞
- 技术栈
- csharp, github-actions
调研方向
首先查看 docfx.json、commitlint.yml、现有的 GitHub Actions 工作流以及相关 issue #845。该 issue 包含多个关于 CI、分支、标签和 API 文档的可行方案，但范围尚未确定。要视为完成，需要达成一致的设计，并通过有效的验证确保生成的文档链接仍然有效。
由索引模型根据 Issue 内容生成。
描述
This Docs/CI Enhancement targets to keep pre / development Branch Docs + Releases API:
- cleanly seperated on their branch (intellisense/markdown suggestion support)
- allow valid API docs and source code linking in docs
[!IMPORTANT]
docfx docs generation will fail completly or produce invalid Links if we include the metadata step on a branch that doesn't include the to be linked file or src code!
To Ensure the latest docs PR (find linked in Additional Information Section) will not fall on our toes in the future or cause unnessesary additional (automate-able) work for us, we should consider:
-
GH Action for PR's md docs changes: If there are only md docs changes (our current build not includes API docs) This should get triggered and add a PR for maybe cherry picking those commits from development onto master? but this will potentially be causing invalid links as soon as we step on to use API docs!
-
Enhance/Ensure proper Commit Labels: We should then explicitly keep our commits cleanly seperated and scoped/categorized properly, which would include such relevant changes. It's possible for the commitlint.yml from what I readed by now, to add more allowed labels or similar but we should have this discussed and decided properly, what we want and maybe find ways to do this, which I maybe did possibly not consider here.
-
GH Action: Ensure DocFx correct build for API metadata: Pay Attention as soon as we might want to use generate xml docs from any source code via metadata!
Produce and add API Docs after changes on non-master-merge PR branches:- create the API them in this case after their source branch got a relevant PR merge
- have all docfx docs produced and merged to master (?) or @andrerav what do you think of reusing the
gh-pagesbranch for our docs product then 🤔 ? possibly this is the cleanest way...
-
Review & Add DocFx
ContentSetup for API version support:I havn't been successfull by now with the
output/destsettings indocfx.jsonwhich are linted asdepreciatedbut I see many others still use them and I think this is required to have a proper xml API output control for this 🤔-
Possibly I will need to ask the docfx team for help, to come to a working setup, but my targeted idea would be something like this in our github.io web docs then:
-
Additional Information
- #845
@DocSvartz @stagep @andrerav
- 主要语言
- C#
- 星标
- 5.2k
- 派生
- 411
- 平均合并
- 1 天 8 小时
- 30 天内合并 PR
- 4
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
MapsterMapper/Mapster 的其他 Issue
-
.NET Matrix未关闭
难度 2/5 1-3 小时 新手友好度 72/100
MapsterMapper/Mapster#1003 ·
-
难度 3/5 1-2 天 新手友好度 58/100
MapsterMapper/Mapster#1024 · 1 条评论 ·
-
[Mapster Tool] Add support for global:: to disambiguate type names in generated mappers可能已有人在做 关联的 PR 仍在进行中或已合并。 未关闭improvement
难度 3/5 1-2 天 新手友好度 65/100
MapsterMapper/Mapster#1020 · 5 条评论 ·
-
Mapster.Tool - PropertySettingBuilder.Map(member, mapFunc, targetPropertyName) method is not working as expected!可能已有人在做 关联的 PR 仍在进行中或已合并。 未关闭
难度 3/5 1-2 天 新手友好度 68/100
MapsterMapper/Mapster#1017 · 6 条评论 ·
-
难度 3/5 1-2 天 新手友好度 57/100
MapsterMapper/Mapster#1007 · 5 条评论 ·
查看 MapsterMapper/Mapster 的全部 Issue
相似的 Issue
-
dev/release: verify-release-candidate.sh runs 0 Java tests with Debian's Maven可能已有人在做 @kou 今天认领。 未关闭Type: bug
难度 2/5 1-3 小时 新手友好度 72/100
apache/arrow-adbc#4947 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 68/100
microsoft/fluentui-blazor#5535 ·
维护者通常 1 天内回复
-
难度 1/5 1-3 小时 新手友好度 74/100
AvaloniaUI/Avalonia#22582 ·
维护者通常 2 天内回复
-
:watch: Not Triaged CAC
难度 2/5 1-3 小时 新手友好度 78/100
dotnet/AspNetCore.Docs#38001 ·
维护者通常 1 天内回复
-
HTTP logging truncates catch-all route parameters in the formatted request path可能已有人在做 @johnkaram02 今天认领。 未关闭area-telemetry untriaged
难度 2/5 1-3 小时 新手友好度 78/100
dotnet/extensions#7883 ·
维护者通常 1 天内回复