diff --git a/doc/ext/__init__.py b/doc/ext/__init__.py new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/doc/ext/nova_todo.py b/doc/ext/nova_todo.py new file mode 100644 index 000000000000..7a06b1bf9eac --- /dev/null +++ b/doc/ext/nova_todo.py @@ -0,0 +1,86 @@ +# -*- coding: utf-8 -*- +# This is a hack of the builtin todo extension, to make the todo_list more user friendly + +from sphinx.ext.todo import * +from docutils.parsers.rst import directives + +def _(s): + return s + +def process_todo_nodes(app, doctree, fromdocname): + if not app.config['todo_include_todos']: + for node in doctree.traverse(todo_node): + node.parent.remove(node) + + # Replace all todolist nodes with a list of the collected todos. + # Augment each todo with a backlink to the original location. + env = app.builder.env + + if not hasattr(env, 'todo_all_todos'): + env.todo_all_todos = [] + + my_todo_list = nodes.bullet_list("", nodes.Text('','')); + + # remove the item that was added in the constructor, since I'm tired of + # reading through docutils for the proper way to construct an empty list + my_todo_list.remove(my_todo_list[0]) + + my_todo_list.set_class('todo_list') + for node in doctree.traverse(todolist): + if not app.config['todo_include_todos']: + node.replace_self([]) + continue + + content = [] + + for todo_info in env.todo_all_todos: + para = nodes.paragraph() + filename = env.doc2path(todo_info['docname'], base=None) + + # Create a reference + newnode = nodes.reference('', '') + + link = _('%s, line %d') % (filename, todo_info['lineno']); + innernode = nodes.emphasis(link, link) + newnode['refdocname'] = todo_info['docname'] + + try: + newnode['refuri'] = app.builder.get_relative_uri( + fromdocname, todo_info['docname']) + newnode['refuri'] += '#' + todo_info['target']['refid'] + except NoUri: + # ignore if no URI can be determined, e.g. for LaTeX output + pass + + newnode.append(innernode) + para += newnode + para.set_class("link") + + todo_entry = todo_info['todo'] + + env.resolve_references(todo_entry, todo_info['docname'], app.builder) + + item = nodes.list_item("", para) + todo_entry[1].set_class("details") + item.append(todo_entry[1]) + + my_todo_list.insert(0, item) + + + node.replace_self(my_todo_list) + +def setup(app): + app.add_config_value('todo_include_todos', False, False) + + app.add_node(todolist) + app.add_node(todo_node, + html=(visit_todo_node, depart_todo_node), + latex=(visit_todo_node, depart_todo_node), + text=(visit_todo_node, depart_todo_node)) + + app.add_directive('todo', Todo) + app.add_directive('todolist', TodoList) + app.connect('doctree-read', process_todos) + app.connect('doctree-resolved', process_todo_nodes) + app.connect('env-purge-doc', purge_todos) + diff --git a/doc/source/_static/tweaks.css b/doc/source/_static/tweaks.css new file mode 100644 index 000000000000..d1cbed96d104 --- /dev/null +++ b/doc/source/_static/tweaks.css @@ -0,0 +1,44 @@ +ul.todo_list { + list-style-type: none; + margin: 0; + padding: 0; +} + +ul.todo_list li { + display: block; + margin: 0; + padding: 7px 0; + border-top: 1px solid #eee; +} + +ul.todo_list li p { + display: inline; +} + +ul.todo_list li p.link { + font-weight: bold; +} + +ul.todo_list li p.details { + font-style: italic; +} + +ul.todo_list li { +} + +div.admonition { + border: 1px solid #FF6666; +} + +div.admonition p.admonition-title { + background-color: #FF6666; + border-bottom: 1px solid #FF6666; +} + +em { + font-style: normal; +} + +table.docutils { + font-size: 11px; +} \ No newline at end of file diff --git a/doc/source/_theme/layout.html b/doc/source/_theme/layout.html new file mode 100644 index 000000000000..ed1cab0a6e39 --- /dev/null +++ b/doc/source/_theme/layout.html @@ -0,0 +1,2 @@ +{% extends "sphinxdoc/layout.html" %} +{% set css_files = css_files + ['_static/tweaks.css'] %} diff --git a/doc/source/_theme/theme.conf b/doc/source/_theme/theme.conf new file mode 100644 index 000000000000..e039fe01f99d --- /dev/null +++ b/doc/source/_theme/theme.conf @@ -0,0 +1,5 @@ +[theme] +inherit = sphinxdoc +stylesheet = sphinxdoc.css +pygments_style = friendly + diff --git a/doc/source/conf.py b/doc/source/conf.py index 3f6ca2313813..177c6568edb0 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -17,13 +17,14 @@ import sys, os # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../../')) - +sys.path.insert(0, '../') +sys.path.insert(0, './') # -- General configuration ----------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'ext.nova_todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig'] todo_include_todos = True # Add any paths that contain templates here, relative to this directory. @@ -99,7 +100,8 @@ modindex_common_prefix = ['nova.'] # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = 'sphinxdoc' +html_theme_path = ["."] +html_theme = '_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the