On Thu, 25 Jan 2024, Jonathan Corbet <corbet@xxxxxxx> wrote: > Anna-Maria Behnsen <anna-maria@xxxxxxxxxxxxx> writes: >> 4. Add a warning banner at the existing documentation and prepare >> everything to get the timer documentation to the proper place and >> create a place for timer documentation below the current structure. >> >> The benefit of 4. for me is, that there is this warning banner at the >> top. So this suggests the reader, that this has to be revisited before >> relying on it for 100%. This banner might also remind the original >> author/technically deep involved developer that this should be >> updated. > > The best thing, of course, is to just fix all of the documentation and > make it perfect now :) > > Failing that, the banners are fine IMO. They mark possibly obsolete > docs, warning readers, and also just might, in an optimal world, inspire > somebody else to work to improve the situation. > > I've thought for a while that we should have a standard warning or two > along these lines, like Wikipedia does, but of course haven't done > anything about it. One approach could be to use the todo extension [1], and use todo directives instead of warnings. With todo_include_todos config set to True, you get the banners in the code, but it's more of an invitation for people to fix them. Maybe. :) BR, Jani. [1] https://www.sphinx-doc.org/en/master/usage/extensions/todo.html -- Jani Nikula, Intel
