Sphinx待办事项框不显示

Question

在sphinx中，我无法让待办事项列表显示出来。这是我现在的设置：

.. todo:: blah blah blah

conf.py

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

我在conf.py里尝试了 sphinx.ext.todo=True，但是当我运行 make html 时却出现了语法错误。

Answer 1

有三件事情是必要的。

在 conf.py 文件中：

• 添加 'sphinx.ext.todo' 这个扩展。
• 添加 "todo_include_todos = True" 这个参数。

必须存在一个名为 todo.rst 的文件，并且里面要有以下指令：

.. todolist::

Answer 2

基本的答案是由daveydave400提供的，但我想添加一些详细的步骤说明：

1) 创建一个自定义样式表，比如叫做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) 把它复制到你的Sphinx文档的source/_static目录下（在你的情况下可能是.static，可以查看conf.py中的html_static_path）

3) 编辑你的Sphinx文档的conf.py文件；在里面添加

html_style = 'custom.css'

这对我有效！

如果你想在多个项目中使用彩色的待办事项框，可以考虑自己写一个主题：

1) 在Lib\site-packages\sphinx\themes目录下创建一个custom文件夹

2) 在里面创建一个theme.conf文件，内容为

[theme]
inherit = default
stylesheet = custom.css

3) 创建一个custom\static子目录，把上面提到的custom.css文件放进去，并重命名为custom.css_t

4) 在conf.py中设置html_theme = 'custom'

实际上，你可以给任何通用的提示框上色。例如，你在文本中有：

.. admonition:: Information

   some info

(在“some info”前的空行是必需的)

你可以在custom.css（或者custom.css_t，如果你自己做主题的话）中添加：

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
}

来给信息提示框上色

Answer 3

根据这份文档，你需要在配置中设置 todo_include_todos。

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

如果你遇到语法错误，可以尝试一下（就像上面文档中提到的示例那样）：

.. todo::

    blah
    blah

补充：

这个网站的样子和你看到的不一样，因为那个网站用了自定义的CSS来实现这个效果。我查看了sphinx的源代码，发现“Pyramid”主题是唯一提到TODO样式的主题，但显然你提到的网站使用的是默认主题。那个网站有它自己的CSS文件。你应该可以把自己的CSS文件放到“doc/source/_static”目录下，然后在你的conf.py中添加类似这样的内容来引入它：

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

特别注意他们CSS文件中关于 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
}