Todos¶
The todo directive marks an outstanding task inline in the documentation,
rendered as an admonition titled Todo;
todolist gathers every todo in the project into one place,
each entry followed by a link back to where it was written.
These come from Sphinx’s own sphinx.ext.todo extension. ubCode implements them natively, with nothing to install — they only need the extension name listed in your parsing configuration:
[parse]
extensions = ["sphinx.ext.todo"]
A todo¶
In reStructuredText the task can be the directive’s argument or its body; in MyST, write it in the body (see Todos).
Todos
.. todo:: Decide whether this specimen stays on its own page.
.. todo::
Add a specimen for every option the directive takes.
Todo
Decide whether this specimen stays on its own page.
Todo
Add a specimen for every option the directive takes.
```{todo}
Decide whether this specimen stays on its own page.
```
```{todo}
Add a specimen for every option the directive takes.
```
The MyST form renders live in the MyST todos.
Each block takes the usual admonition options,
and gets an anchor so a todolist can link back to it.
How that anchor is named differs from a Sphinx build (see Todos).
Warning
:name: on a todo aborts a full sphinx-build
with an unhandled error inside sphinx.ext.todo itself —
it registers the block’s name twice.
ubCode accepts it and treats it as any other admonition name,
but do not use it in a source tree you also build with Sphinx.
Every todo already gets an automatic anchor, so you rarely need it.
The list of todos¶
todolist lists every todo in the project, whichever page it is on,
so the list below holds this page’s todos, those of its MyST twin, and any other page’s, such as the tutorial’s.
This site sets todo_link_only,
so each entry is followed by a link to where it was written, without the file’s path.
The list of todos
.. todolist::
Todo
Decide whether this specimen stays on its own page.
Todo
Add a specimen for every option the directive takes.
Todo
Decide whether this specimen stays on its own page.
Todo
Add a specimen for every option the directive takes.
Todo
Extend this tutorial with a section on importing existing needs from a JSON export, and on tracking progress over time with a metrics view.
```{todolist}
```
The MyST twin does not repeat this list: a second list would hold the same entries.
Note
ubc build pdf cannot place a todolist yet
(it reports one as build.pdf_block_unsupported),
so the PDF shows this specimen’s source only.
Set [parse].todo_include_todos = false to hide every todo and every list,
and todo_link_only = true to drop the path from each entry
(see Parsing).
Note that ubCode renders todos by default where a full sphinx-build
hides them unless todo_include_todos is set —
set the value explicitly in a project that builds with both.