DESDEO
DESDEO copied to clipboard
[IDEA] Documentation tool and style
-
What is the current behavior? We are currently utilizing sphinx for documentation. Each sub-project in DESDEO has currently its own implementation of sphinx-based documentation. Each one of these needs to be always manually modified. Moreover, our documentation style should be more clearly structured.
-
Describe the solution you'd like We should move to a simpler tool and adopt a clear (and tested) documentation structure. We have previously already discussed MkDocs, which is a promising candidate for an alternative tool. As for the structure of the documentation, we should follow the diataxis philosophy.
-
What is the motivation/use case for changing the behavior? Sphinx is complicated. With a simpler tool, the bar to write and contribute to the documentation will be lowered. With a clear structure for the documentation, we, and users, have also a clearer picture of where to find relevant content. Diataxis is followed by other projects as well, it is tried and tested, and will meet the expectations of many users when it comes to documentation.
-
Describe alternatives you've considered Sphinx has been the only real alternative we have considered and used. It works, but the features it offers at the cost of added complexity are not justified for our use-case.
-
Additional context This is related to the structure of the project. With a monolithic structure (discussed in #73 ), we will also end up with a single documentation to work on, which facilitates things a lot.