Sphinx todo box not showing

Question

In sphinx, I can not make the todo list show. Here is what I have:

.. todo:: blah blah blah

conf.py

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
]

I tried sphinx.ext.todo=True in conf.py, but then I get syntax errors when I make html.

Answer 1

Based on this documentation you have to set the todo_include_todos in the configuration.

http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos

If you get syntax errors maybe try (as in the note example linked to from the docs above):

.. todo::

    blah
    blah

Edit:

It doesn't look the same as in that site because that site has applied customed CSS to get that. I looked at the sphinx source code and the "Pyramid" theme is the only theme that mentions the TODO styles, but you can obviously see that the site you mentioned uses the default theme. That site has it's own CSS file. You should be able to add your own CSS file to your "doc/source/_static" directory and add something like this to your conf.py to include it:

def setup(app):
    app.add_stylesheet('my_styles.css')

Specifically notice the section of their CSS file for div.admonition-todo:

div.admonition-todo {
border-top: 2px solid red;
border-bottom: 2px solid red;
border-left: 2px solid red;
border-right: 2px solid red;
background-color: #ff6347
}

Answer 2

The basic answer is given by daveydave400, but I want to add step-by-step instructions:

1) make your custom style-sheet, say custom.css

@import url("default.css");


div.admonition-todo {
    border-top: 2px solid red;
    border-bottom: 2px solid red;
    border-left: 2px solid red;
    border-right: 2px solid red;
    background-color: #ff6347
}

2) copy it to source/_static directory of your sphinx documentation (it may be .static in your case, look at html_static_path in conf.py)

3) edit conf.py of your sphinx documentation; add there

html_style = 'custom.css'

It worked for me!

If you want to use colored todo boxes in many projects, consider writing your own theme:

1) create directory custom in Lib\site-packages\sphinx\themes

2) create there theme.conf file containing

[theme]
inherit = default
stylesheet = custom.css

3) create custom\static sub-directory, put there custom.css file described above, and rename it to custom.css_t

4) in conf.py make html_theme = 'custom'

In fact you can color ANY generic admonition. E.g., you have in the text:

.. admonition:: Information

   some info

(the empty line before "some info" is essential)

you can add to the custom.css (or custom.css_t, if you make your own theme):

div.admonition-information {
    border-top: 2px solid green;
    border-bottom: 2px solid green;
    border-left: 2px solid green;
    border-right: 2px solid green;
    background-color: #63cc47
}

to color information admonitions

Answer 3

Three things are necessary.

In conf.py:

• Add the 'sphinx.ext.todo' extension.
• Add the "todo_include_todos = True" parameter.

The todo.rst file with the following directive must exist:

.. todolist::