Display the documents titles of the todos in the list of all todo directives

[dbitouze]

Is your feature request related to a problem? Please describe. The list of all todo directives is too little contextualized.

Describe the solution you'd like I'd like the list of all todo directives to display the document's title to each of the todos, in order to make them more contextualized. OK, the todo_link_only = False gives a bit more context with the file path but the latter may be cryptic and much less informative than the document's title.

[tk0miya]

-0; I don't understand how the document's title useful to manage TODOs. I think what "context" users needed is different for each other. For me, it's not important.

[dbitouze]

I don't understand how the document's title useful to manage TODOs.

The motivation of my request is the following: I'm using Sphinx for a LaTeX FAQ (in French) which currently is in a very incomplete state (many questions from a very old French FAQ that need to be updated, many questions from the English FAQ not yet translated, etc.) and still needs a lot of work (about 1100 questions). In many questions, contributors have left or will leave TODOs that are listed thanks to the sphinx.ext.todo extension (as you can see here) with the hope other contributors will fix these TODOs. But the TODOs are often too little contextualized by their content to let a potential contributor say: "Yes, I could help for this TODO!"; by contrast, the title of the document (of the FAQ in this case) would probably let this potential contributor immediately know whether he could help or not.

[dbitouze]

BTW, another improvement would be to group the list of todo directives by the sections they belong to. Compare our old way (based on DokuWiki) and our new way (based on Sphinx) of displaying todos.

[picnixz]

PR is welcomed. Instead of showing the document name, I think it would be better to actually have a way to specify a specific title (maybe there is, I never used that directive).

By default, we could keep the current behaviour. Add a configuration variable which automatically adds the file path or the document name (like todo_show_default_context = 'docname' or 'filename'). A user could override the default context at the directive level via :context: whatever and could also use some special context name like :context: %(filename)s (and could still use the special word %(filename)s by writing something like %%(filename)s).

I can have a look at it before the end of the year but anyone is free to submit a PR that I would review!

[dbitouze]

PR is welcomed. Instead of showing the document name, I think it would be better to actually have a way to specify a specific title

Do you mean the title of the document (of the page)? If so, I completely agree.

(maybe there is, I never used that directive).

AFAICS, no.

By default, we could keep the current behaviour. Add a configuration variable which automatically adds the file path or the document name (like todo_show_default_context = 'docname' or 'filename'). A user could override the default context at the directive level via :context: whatever and could also use some special context name like :context: %(filename)s (and could still use the special word %(filename)s by writing something like %%(filename)s).

IMO, the best would be the title of the document (page).

[picnixz]

Do you mean the title of the document (of the page)? If so, I completely agree.

You said you wanted to display the document title for each todo to make them contextualised. I suggest that you can show the document title, the filepath or anything else by using :context: (or any other relevant option name).

I still think that a context should not be forced by default but a default context could be assumed (instead of always adding :context: %(docname)s everywhere, you could configure the extension so that it is assumed automatically, unless the directive already contains that option).

I think :group: or :in: should be used instead of :context: so that it could be then shown as groups (like multiple todos across multiple files but all of them are part of the same todo group). You could also add multiple groups separated by a comma.