started Qt documentation extension

This commit is contained in:
Luke Campagnola 2013-05-30 12:57:03 -04:00
parent 59bbe0127e
commit aff70070ac
2 changed files with 146 additions and 1 deletions

143
doc/extensions/qt_doc.py Normal file
View File

@ -0,0 +1,143 @@
"""
Extension for building Qt-like documentation.
- Method lists preceding the actual method documentation
- Inherited members documented separately
- Members inherited from Qt have links to qt-project documentation
- Signal documentation
"""
def setup(app):
## Add new configuration options
app.add_config_value('todo_include_todos', False, False)
## Nodes are the basic objects representing documentation directives
## and roles
app.add_node(Todolist)
app.add_node(Todo,
html=(visit_todo_node, depart_todo_node),
latex=(visit_todo_node, depart_todo_node),
text=(visit_todo_node, depart_todo_node))
## New directives like ".. todo:"
app.add_directive('todo', TodoDirective)
app.add_directive('todolist', TodolistDirective)
## Connect callbacks to specific hooks in the build process
app.connect('doctree-resolved', process_todo_nodes)
app.connect('env-purge-doc', purge_todos)
from docutils import nodes
from sphinx.util.compat import Directive
from sphinx.util.compat import make_admonition
# Just a general node
class Todolist(nodes.General, nodes.Element):
pass
# .. and its directive
class TodolistDirective(Directive):
# all directives have 'run' method that returns a list of nodes
def run(self):
return [Todolist('')]
# Admonition classes are like notes or warnings
class Todo(nodes.Admonition, nodes.Element):
pass
def visit_todo_node(self, node):
self.visit_admonition(node)
def depart_todo_node(self, node):
self.depart_admonition(node)
class TodoDirective(Directive):
# this enables content in the directive
has_content = True
def run(self):
env = self.state.document.settings.env
# create a new target node for linking to
targetid = "todo-%d" % env.new_serialno('todo')
targetnode = nodes.target('', '', ids=[targetid])
# make the admonition node
ad = make_admonition(Todo, self.name, [('Todo')], self.options,
self.content, self.lineno, self.content_offset,
self.block_text, self.state, self.state_machine)
# store a handle in a global list of all todos
if not hasattr(env, 'todo_all_todos'):
env.todo_all_todos = []
env.todo_all_todos.append({
'docname': env.docname,
'lineno': self.lineno,
'todo': ad[0].deepcopy(),
'target': targetnode,
})
# return both the linking target and the node itself
return [targetnode] + ad
# env data is persistent across source files so we purge whenever the source file has changed.
def purge_todos(app, env, docname):
if not hasattr(env, 'todo_all_todos'):
return
env.todo_all_todos = [todo for todo in env.todo_all_todos
if todo['docname'] != docname]
# called at the end of resolving phase; we will convert temporary nodes
# into finalized nodes
def process_todo_nodes(app, doctree, fromdocname):
if not app.config.todo_include_todos:
for node in doctree.traverse(Todo):
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
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)
description = (
('(The original entry is located in %s, line %d and can be found ') %
(filename, todo_info['lineno']))
para += nodes.Text(description, description)
# Create a reference
newnode = nodes.reference('', '')
innernode = nodes.emphasis(('here'), ('here'))
newnode['refdocname'] = todo_info['docname']
newnode['refuri'] = app.builder.get_relative_uri(
fromdocname, todo_info['docname'])
newnode['refuri'] += '#' + todo_info['target']['refid']
newnode.append(innernode)
para += newnode
para += nodes.Text('.)', '.)')
# Insert into the todolist
content.append(todo_info['todo'])
content.append(para)
node.replace_self(content)

View File

@ -18,6 +18,7 @@ import sys, os
# documentation root, use os.path.abspath to make it absolute, like shown here.
path = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, os.path.join(path, '..', '..'))
sys.path.insert(0, os.path.join(path, '..', 'extensions'))
# -- General configuration -----------------------------------------------------
@ -26,7 +27,7 @@ sys.path.insert(0, os.path.join(path, '..', '..'))
# 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.viewcode']
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'qt_doc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -215,3 +216,4 @@ man_pages = [
('index', 'pyqtgraph', 'pyqtgraph Documentation',
['Luke Campagnola'], 1)
]