eclipse-score / eclipse-score/docs-as-code

Sphinx collections cannot be nested

未关闭
#305 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
主要语言
Python
星标
11
派生
33
平均合并
23 小时 52 分钟
30 天内合并 PR
52

描述

[When I integrate the docs-as-code module in reference-integration](https://github.com/eclipse-score/reference_integration/pull/43), the :docs_combo_experimental build fails:

```
/home/runner/work/reference_integration/reference_integration/docs/_collections/score_docs_as_code/docs/index.rst:6: WARNING: undefined label: '_collections/score_process/process/index' [ref.ref]
```

The problem is the [sphinx-collections](https://sphinx-collections.readthedocs.io/en/latest/) extension which is used in reference-integration and in docs-as-code. When docs-as-code is not the documentation root, it doesn't find the process collection.

Short-term we can simply remove it from docs-as-code since we only really need it reference-integration currently.

Long-term we want a solution which just works for any module which wants to use it. I see two option: Adapt sphinx-collections to handle such a use-case. Stop using sphinx-collections and implement the combo differently.

贡献指南

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

调研方向

从失败的参考 docs/_collections/score_docs_as_code/docs/index.rst 和 reference-integration PR 43 中的 :docs_combo_experimental build 开始。了解 sphinx-collections 在 docs-as-code 和 reference-integration 中的配置方式,然后评估 issue 中描述的短期移除方案和长期替代方案。当嵌套 collections 能够用于模块,或者 build 不再报告 undefined process-collection label 时,即表示完成。

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

评估

技术栈
python
领域
documentation
Issue 类型
缺陷
难度
5/5
预计耗时
一周以上
活跃度
停滞
描述清晰度
需要澄清
新手友好度
25/100

把新 issue 发到你的邮箱

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