x/wsme
Code Issues Proposed changes

Add samples_slot option to TypeDocumenter

Browse Source 
Allow the output of the TypeDocumenter to come in different
orders, depending on the sample-slot option. Default to
showing samples after the rendered docstring, but also
allow it to come before the docstring by setting the
option to 'before-docstring'. Use 'none' to disable the
sample output for a type entirely.
This commit is contained in:
Doug Hellmann 2012-12-07 17:23:29 -05:00
parent c5c7f6df37
commit c1440fff51
1 changed files with 68 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
wsme/sphinxext.py
View File

@ -162,16 +162,37 @@ class AttributeDirective(PyClassmember):
] ]
def check_samples_slot(value):
"""Validate the samples_slot option to the TypeDocumenter.
Valid positions are 'before-docstring' and
'after-docstring'. Using the explicit 'none' disables sample
output. The default is after-docstring.
"""
if not value:
return 'after-docstring'
val = directives.choice(
value,
('none', # do not include
'before-docstring', # show samples then docstring
'after-docstring', # show docstring then samples
))
return val
class TypeDocumenter(autodoc.ClassDocumenter): class TypeDocumenter(autodoc.ClassDocumenter):
objtype = 'type' objtype = 'type'
directivetype = 'type' directivetype = 'type'
domain = 'wsme' domain = 'wsme'
required_arguments = 1 required_arguments = 1
default_samples_slot = 'after-docstring'
option_spec = dict(autodoc.ClassDocumenter.option_spec, **{ option_spec = dict(
'protocols': lambda l: [v.strip() for v in l.split(',')] autodoc.ClassDocumenter.option_spec,
}) **{'protocols': lambda l: [v.strip() for v in l.split(',')],
'samples-slot': check_samples_slot,
})
@classmethod @classmethod
def can_document_member(cls, member, membername, isattr, parent): def can_document_member(cls, member, membername, isattr, parent):
@ -199,34 +220,51 @@ class TypeDocumenter(autodoc.ClassDocumenter):
return False return False
def add_content(self, more_content, no_docstring=False): def add_content(self, more_content, no_docstring=False):
super(TypeDocumenter, self).add_content( # Check where to include the samples
more_content, no_docstring) samples_slot = self.options.samples_slot or self.default_samples_slot
protocols = get_protocols(
self.options.protocols or self.env.app.config.wsme_protocols
)
content = []
if protocols:
sample_obj = make_sample_object(self.object)
content.extend([
l_(u'Data samples:'),
u'',
u'.. cssclass:: toggle',
u''
])
for name, protocol in protocols:
language, sample = protocol.encode_sample_value(
self.object, sample_obj, format=True)
content.extend([
name,
u' .. code-block:: ' + language,
u'',
])
content.extend((
u' ' * 8 + line for line in sample.split('\n')))
for line in content:
self.add_line(line, u'<wsme.sphinxext')
self.add_line(u'', '<wsme.sphinxext>') print 'SAMPLES SLOT:', self.options.samples_slot
def add_docstring():
super(TypeDocumenter, self).add_content(
more_content, no_docstring)
def add_samples():
protocols = get_protocols(
self.options.protocols or self.env.app.config.wsme_protocols
)
content = []
if protocols:
sample_obj = make_sample_object(self.object)
content.extend([
l_(u'Data samples:'),
u'',
u'.. cssclass:: toggle',
u''
])
for name, protocol in protocols:
language, sample = protocol.encode_sample_value(
self.object, sample_obj, format=True)
content.extend([
name,
u' .. code-block:: ' + language,
u'',
])
content.extend((
u' ' * 8 + line for line in sample.split('\n')))
for line in content:
self.add_line(line, u'<wsme.sphinxext')
self.add_line(u'', '<wsme.sphinxext>')
if samples_slot == 'after-docstring':
add_docstring()
add_samples()
elif samples_slot == 'before-docstring':
add_samples()
add_docstring()
else:
add_docstring()
class AttributeDocumenter(autodoc.AttributeDocumenter): class AttributeDocumenter(autodoc.AttributeDocumenter):