eclipse-score / eclipse-score/docs-as-code
Sphinx collections cannot be nested
- Dominant language
- Python
- Stars
- 10
- Forks
- 32
- Avg merge
- 23h 52m
- Merged PRs (30d)
- 52
Description
[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.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the failing docs/_collections/score_docs_as_code/docs/index.rst reference and the :docs_combo_experimental build in reference-integration PR 43. Read how sphinx-collections is configured in docs-as-code and reference-integration, then assess the short-term removal and long-term alternatives described in the issue. Done means nested collections work for modules or the build no longer reports the undefined process-collection label.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100