teemtee
Migrate the `generate_stories` script to tmt sphinx domain documenter
This is the first example case of how the sphinx tmt domain is utilized.
Depends on: https://github.com/teemtee/tmt/pull/4287
sphinx domain documenter
Not sure what is this? Another level of indirection by hiding scripts into extensions?
If something in Sphinx breaks, I have no idea how to debug this. With standalone scripts there is no such problem.
sphinx domain documenter
Not sure what is this? Another level of indirection by hiding scripts into extensions?
If something in Sphinx breaks, I have no idea how to debug this. With standalone scripts there is no such problem.
There are issues with generating rst files instead of hooking into the directives directly:
- when overwriting the files, it will always be out-of-date, and the whole documentation is being rebuilt every time. This completely kills usage of
sphinx-autobuild - the sources of the rst are distributed across multiple files, so we cannot use any native approaches to link the sources related
- overall it is slower compared to documenting the items as they are requested by sphinx
- it prevents us from optimizing the import of tmt to be done only once
Additionally there are some features of the domain that we would want:
- avoid global targets and use explicit domain-based targets, e.g.
:tmt:story:...instead of:ref:... - allow other users to use the implementations we make here if they want to use stories, etc. in a similar way
Reference:
- https://www.sphinx-doc.org/en/master/development/tutorials/adding_domain.html
If I am to choose documentation system in 2025, I would choose something different, markdown based. Maybe even written in Go. Sphinx is way too complicated that even simple things like https://github.com/sphinx-doc/sphinx/issues/8709 are impossible to fix for many years.
If I am to choose documentation system in 2025, I would choose something different, markdown based
Sphinx is markdown compliant with myst-parser.
Sphinx is way too complicated that even simple things like sphinx-doc/sphinx#8709 are impossible to fix for many years.
I did not see in that discussion any mention of sphinx.ext.autosectionlabel. We could debate on the actual benefits and disadvantages of the ecosystem, but I doubt a better one would come out ahead of it once we put them to a fair head-to-head. Feel free to prove me wrong on that, but do so in the issues/discussion section.
Ecosystem is a too broad concept. I mean the whole Sphinx model doesn't have a single picture to describe its data processing pipeline and input/output artifacts at each stage. That's why it is hard to impossible to fix things. It takes way too much time to discuss, understand and agree.