class ReferenceToc(object):
def __init__(self, filename):
self.table = tb.TableData()
self.content = RstCloth()
self.spec = self._process_spec(filename)
self._process_data()
def _process_spec(self, spec):
o = []
with open(spec, 'r') as f:
data = yaml.load_all(f)
for datum in data:
if datum['description'] is None:
datum['description'] = ''
o.append(datum)
o.sort(key=lambda o: o['name'])
return o
def _process_data(self):
self.table.add_header(['Name', 'Description'])
self.content.directive('class', 'hidden', block='toc')
self.content.newline(block='toc')
self.content.directive('toctree', fields=[('titlesonly', '')], indent=3, block='toc')
self.content.newline(block='toc')
for ref in self.spec:
self.content.content(ref['file'], 6, block='toc')
self.table.add_row([ ref['name'], ref['description'] ])
class CustomTocTree(object):
def __init__(self, filename, sort=False):
self.spec = self._process_spec(filename, sort)
self.table = None
self.contents = None
self.dfn = None
def build_table(self):
self.table = tb.TableData()
self.table.add_header(['Name', 'Description'])
def build_dfn(self):
self.dfn = RstCloth()
def build_contents(self):
self.contents = RstCloth()
self.contents.directive('class', 'hidden')
self.contents.newline()
self.contents.directive('toctree', fields=[('titlesonly', '')], indent=3)
self.contents.newline()
def _process_spec(self, spec, sort=False):
o = []
with open(spec, 'r') as f:
data = yaml.load_all(f)
for datum in data:
if datum['description'] is None:
datum['description'] = ''
if sort is False:
pass
elif 'name' not in datum:
sort = False
o.append(datum)
if sort is True:
o.sort(key=lambda o: o['name'])
return o
def finalize(self):
for ref in self.spec:
if self.table is not None:
self.table.add_row([ ref['name'], ref['description'] ])
if self.contents is not None:
self.contents.content(ref['file'], 6, block='toc')
if self.dfn is not None:
if 'name' in ref:
text = ref['name']
else:
text = None
link = self.dfn.role('doc', ref['file'], text)
self.dfn.definition(link, ref['description'], bold=False)
self.dfn.newline()
def generate_params(params, fn):
r = RstCloth()
lconf = load_conf()
basename = os.path.basename(fn)
params.sort(key=lambda p: p['position'])
# Begin by generating the table for web output
r.directive('only', '(html or singlehtml or dirhtml)', block='htm')
r.newline(block='htm')
# { filename: { $name: <param> } }
ext_params = {}
processed_params = []
for param in params:
if 'file' in param:
pos = param['position']
if param['file'] not in ext_params:
fn, ext = populate_external_param(param['file'],
basename,
lconf.build.paths.projectroot,
lconf.build.paths.source)
ext_params[fn] = ext
param = ext_params[lconf.build.paths.source + param['file']][param['name']]
param['position'] = pos
processed_params.append(param)
r.content(generate_param_table(processed_params), indent=3, block='html')
r.newline(block='htm')
# Then generate old-style param fields for non-web output
r.directive('only', '(texinfo or latex or epub)', block='tex')
r.newline(block='tex')
for param in processed_params:
key, val = generate_param_fields(param)
r.field(name=key, value=val, indent=3, wrap=False, block='tex')
r.newline(block='tex')
return r
def render_step_file(input_fn, output_fn=None):
steps = Steps(input_fn)
r = RstCloth()
r.directive('only', 'not latex')
r.newline()
web_output = WebStepsOutput(steps)
web_output.render()
r.content(web_output.rst.get_block(), indent=3, wrap=False)
r.directive('only', 'latex')
r.newline()
print_output = PrintStepsOutput(steps)
print_output.render()
r.content(print_output.rst.get_block(), indent=3, wrap=False)
if output_fn is None:
output_fn = os.path.splitext(input_fn)[0] + '.rst'
r.write(output_fn)
print('[steps]: rendered step include at ' + output_fn)
def generate_release_output(builder, platform, architecture, release):
""" This is the contemporary version of the function used by the generate.py script"""
r = RstCloth()
r.directive('code-block', 'sh', block='header')
r.newline(block='header')
if architecture == 'core':
r.content('curl http://downloads.mongodb.org/{0}/mongodb-{1}-{2}.tgz > mongodb.tgz'.format(platform, builder, release), 3, wrap=False, block='cmd')
else:
r.content('curl http://downloads.10gen.com/linux/mongodb-{0}-subscription-{1}-{2}.tgz > mongodb.tgz'.format(builder, architecture, release), 3, wrap=False, block='cmd')
r.content('tar -zxvf mongodb.tgz', 3, wrap=False, block='cmd')
r.content('cp -R -n mongodb-{0}-subscription-{1}-{2}/ mongodb'.format(builder, architecture, release), 3, wrap=False, block='cmd')
r.newline(block='footer')
return r
def generate_output(builder, platform, version, release):
""" This is the legacy version of the function used by the makefile and CLI infrastructure"""
r = RstCloth()
r.directive('code-block', 'sh', block='header')
r.newline(block='header')
if release == 'core':
r.content('curl http://downloads.mongodb.org/{0}/mongodb-{1}-{2}.tgz > mongodb.tgz'.format(platform, builder, version), 3, wrap=False, block='cmd')
else:
r.content('curl http://downloads.10gen.com/linux/mongodb-{0}-subscription-{1}-{2}.tgz > mongodb.tgz'.format(builder, release, version), 3, wrap=False, block='cmd')
r.content('tar -zxvf mongodb.tgz', 3, wrap=False, block='cmd')
r.content('cp -R -n mongodb-{0}-subscription-{1}-{2}/ mongodb'.format(builder, release, version), 3, wrap=False, block='cmd')
r.newline(block='footer')
return r
class StepsOutput(object):
"""
Base class for rendered step form. The render() method generates the rst in
the internal RstCloth object.
"""
def __init__(self, steps):
if not isinstance(steps, Steps):
raise TypeError
else:
self.steps = steps
self.rst = RstCloth()
self.hook()
def hook(self):
self.indent = 3
def render(self):
for step in self.steps.source_list:
self.heading(step)
self.pre(step)
if isinstance(step['action'], list):
for block in step['action']:
self.code_step(block)
else:
self.code_step(step['action'])
self.post(step)
def pre(self, doc):
if 'pre' in doc:
self.rst.content(doc['pre'], indent=self.indent)
self.rst.newline()
def post(self, doc):
if 'post' in doc:
self.rst.content(doc['post'], indent=self.indent)
self.rst.newline()
def _heading(self, block, override_char=None, indent=0):
if 'heading' in block:
if isinstance(block['heading'], dict):
if 'character' in block['heading']:
pass
else:
block['heading']['character'] = override_char
else:
block['heading'] = { 'text': block['heading'],
'character': override_char }
self.rst.heading(text=block['heading']['text'],
char=block['heading']['character'],
indent=self.indent)
self.rst.newline()
def code_step(self, block):
if 'code' in block and 'content' in block:
raise InvalidStep
self.pre(block)
self._heading(block, override_char='`', indent=self.indent)
if 'code' in block:
if 'language' not in block:
block['language'] = 'none'
self.rst.directive(name='code-block',
arg=block['language'],
content=block['code'],
indent=self.indent)
if 'content' in block:
self.content(block['content'], indent=self.indent)
self.post(block)
def key_name(self):
key_name = os.path.splitext(os.path.basename(self.steps.source_fn))[0]
if key_name.startswith('step-') or key_name.startswith('steps-'):
key_name = key_name.split('-', 1)[1]
return key_name
class TestRstCloth(BaseTestCase):
@classmethod
def setUp(self):
self.r = RstCloth()
def test_adding_without_blocks(self):
self.r._add("foo")
self.assertEqual(self.r.data[0], "foo")
def test_newline(self):
self.r.newline()
self.assertEqual(len(self.r.data), 1)
def test_multi_newline(self):
self.r.newline(count=4)
self.assertEqual(len(self.r.data[0]), 4 - 1)
def test_directive_simple(self):
self.r.directive("test")
self.assertEqual(self.r.data[0], ".. test::")
def test_directive_arg_named(self):
self.r.directive("test", arg="what")
self.assertEqual(self.r.data[0], ".. test:: what")
def test_directive_arg_positional(self):
self.r.directive("test", "what")
self.assertEqual(self.r.data[0], ".. test:: what")
def test_directive_fields(self):
self.r.directive("test", fields=[("a", "b")])
self.assertEqual(self.r.data[0], ".. test::")
self.assertEqual(self.r.data[1], " :a: b")
def test_directive_fields_with_arg(self):
self.r.directive("test", arg="what", fields=[("a", "b")])
self.assertEqual(self.r.data[0], ".. test:: what")
self.assertEqual(self.r.data[1], " :a: b")
def test_directive_fields_multiple(self):
self.r.directive("test", fields=[("a", "b"), ("c", "d")])
self.assertEqual(self.r.data[0], ".. test::")
self.assertEqual(self.r.data[1], " :a: b")
self.assertEqual(self.r.data[2], " :c: d")
def test_directive_fields_multiple_arg(self):
self.r.directive("test", arg="new", fields=[("a", "b"), ("c", "d")])
self.assertEqual(self.r.data[0], ".. test:: new")
self.assertEqual(self.r.data[1], " :a: b")
self.assertEqual(self.r.data[2], " :c: d")
def test_directive_content(self):
self.r.directive("test", content="string")
self.assertEqual(self.r.data[0], ".. test::")
self.assertEqual(self.r.data[1], "")
self.assertEqual(self.r.data[2], " string")
def test_directive_with_multiline_content(self):
self.r.directive("test", content=["string", "second"])
self.assertEqual(self.r.data[0], ".. test::")
self.assertEqual(self.r.data[1], "")
self.assertEqual(self.r.data[2], " string")
self.assertEqual(self.r.data[3], " second")
def test_directive_simple_indent(self):
self.r.directive("test", indent=3)
self.assertEqual(self.r.data, [" .. test::"])
def test_directive_arg_named_indent(self):
self.r.directive("test", arg="what", indent=3)
self.assertEqual(self.r.data, [" .. test:: what"])
def test_directive_arg_positional_indent(self):
self.r.directive("test", "what", indent=3)
self.assertEqual(self.r.data, [" .. test:: what"])
def test_directive_fields_indent(self):
self.r.directive("test", fields=[("a", "b")], indent=3)
self.assertEqual(self.r.data, [" .. test::", " :a: b"])
def test_directive_fields_with_arg_indent(self):
self.r.directive("test", arg="what", fields=[("a", "b")], indent=3)
self.assertEqual(self.r.data, [" .. test:: what", " :a: b"])
def test_directive_fields_multiple_indent(self):
self.r.directive("test", indent=3, fields=[("a", "b"), ("c", "d")])
self.assertEqual(self.r.data,
[" .. test::", " :a: b", " :c: d"])
def test_directive_fields_multiple_arg_indent(self):
self.r.directive("test",
arg="new",
indent=3,
fields=[("a", "b"), ("c", "d")])
self.assertEqual(self.r.data,
[" .. test:: new", " :a: b", " :c: d"])
def test_directive_content_indent(self):
self.r.directive("test", content="string", indent=3)
self.assertEqual(self.r.data, [" .. test::", " ", " string"])
def test_directive_with_multiline_content_indent(self):
self.r.directive("test", indent=3, content=["string", "second"])
self.assertEqual(
self.r.data,
[" .. test::", " ", " string", " second"])
def test_single_role_no_text(self):
ret = self.r.role("test", "value")
self.assertEqual(ret, ":test:`value`")
def test_multi_role_no_text(self):
ret = self.r.role(["test", "role"], "value")
self.assertEqual(ret, ":test:role:`value`")
def test_single_role_text(self):
ret = self.r.role("test", "value", "link")
self.assertEqual(ret, ":test:`link <value>`")
def test_multi_role_text(self):
ret = self.r.role(["test", "role"], "value", "link")
self.assertEqual(ret, ":test:role:`link <value>`")
def test_single_role_no_text_args(self):
ret = self.r.role(name="test", value="value")
self.assertEqual(ret, ":test:`value`")
def test_multi_role_no_text_args(self):
ret = self.r.role(name=["test", "role"], value="value")
self.assertEqual(ret, ":test:role:`value`")
def test_single_role_text_args(self):
ret = self.r.role(name="test", value="value", text="link")
self.assertEqual(ret, ":test:`link <value>`")
def test_multi_role_text_args(self):
ret = self.r.role(name=["test", "role"], value="value", text="link")
self.assertEqual(ret, ":test:role:`link <value>`")
def test_bold(self):
ret = self.r.bold("text")
self.assertEqual(ret, "**text**")
def test_emph(self):
ret = self.r.emph("text")
self.assertEqual(ret, "*text*")
def test_pre(self):
ret = self.r.pre("text")
self.assertEqual(ret, "``text``")
def test_inline_link(self):
ret = self.r.inline_link("text", "link")
self.assertEqual(ret, "`text <link>`_")
def test_footnote_ref(self):
ret = self.r.footnote_ref("name")
self.assertEqual(ret, "[#name]")
def test_codeblock_simple(self):
self.r.codeblock("ls -lha")
self.assertEqual(self.r.data, ["::", " ls -lha"])
def test_codeblock_with_language(self):
self.r.codeblock("ls -lha", language="shell")
self.assertEqual(self.r.data,
[".. code-block:: shell", "", " ls -lha"])
def test_footnote(self):
self.r.footnote("footsnotes", "text of the note")
self.assertEqual(self.r.data[0], ".. [#footsnotes] text of the note")
def test_footnote_with_indent(self):
self.r.footnote("footsnotes", "text of the note", indent=3)
self.assertEqual(self.r.data[0],
" .. [#footsnotes] text of the note")
def test_footnote_with_wrap(self):
self.r.footnote("footsnotes", "the " * 40, wrap=True)
self.assertEqual(
self.r.data[0], ".. [#footsnotes]" + " the" * 14 + "\n " +
" the" * 17 + "\n " + " the" * 9)
def test_definition(self):
self.r.definition("defitem", "this is def text")
self.assertEqual(self.r.data, ["defitem", " this is def text"])
def test_definition_with_indent(self):
self.r.definition("defitem", "this is def text", indent=3)
self.assertEqual(self.r.data, [" defitem", " this is def text"])
def test_title_default(self):
self.r.title("test text")
self.assertEqual(self.r.data, ["=========", "test text", "========="])
def test_title_alt(self):
self.r.title("test text", char="-")
self.assertEqual(self.r.data, ["---------", "test text", "---------"])
def test_heading_one(self):
self.r.heading("test heading", char="-", indent=0)
self.assertEqual(self.r.data, ["test heading", "------------"])
def test_heading_two(self):
self.r.heading("test heading", char="^", indent=0)
self.assertEqual(self.r.data, ["test heading", "^^^^^^^^^^^^"])
def test_h1(self):
self.r.h1("test")
self.assertEqual(self.r.data, ["test", "===="])
def test_h2(self):
self.r.h2("test")
self.assertEqual(self.r.data, ["test", "----"])
def test_h3(self):
self.r.h3("test")
self.assertEqual(self.r.data, ["test", "~~~~"])
def test_h4(self):
self.r.h4("test")
self.assertEqual(self.r.data, ["test", "++++"])
def test_h5(self):
self.r.h5("test")
self.assertEqual(self.r.data, ["test", "^^^^"])
def test_h6(self):
self.r.h6("test")
self.assertEqual(self.r.data, ["test", ";;;;"])
def test_replacement(self):
self.r.replacement("foo", "replace-with-bar")
self.assertEqual(self.r.data, [".. |foo| replace:: replace-with-bar"])
def test_replacement_with_indent(self):
self.r.replacement("foo", "replace-with-bar", indent=3)
self.assertEqual(self.r.data,
[" .. |foo| replace:: replace-with-bar"])
def test_li_simple(self):
self.r.li("foo")
self.assertEqual(self.r.data, ["- foo"])
def test_li_simple_indent(self):
self.r.li("foo", indent=3)
self.assertEqual(self.r.data, [" - foo"])
def test_li_simple_alt(self):
self.r.li("foo", bullet="*")
self.assertEqual(self.r.data, ["* foo"])
def test_li_simple_alt_indent(self):
self.r.li("foo", bullet="*", indent=3)
self.assertEqual(self.r.data, [" * foo"])
def test_li_complex(self):
self.r.li(["foo", "bar"])
self.assertEqual(self.r.data, ["- foo bar"])
def test_li_complex_indent(self):
self.r.li(["foo", "bar"], indent=3)
self.assertEqual(self.r.data, [" - foo bar"])
def test_li_complex_alt(self):
self.r.li(["foo", "bar"], bullet="*")
self.assertEqual(self.r.data, ["* foo bar"])
def test_li_complex_alt_indent(self):
self.r.li(["foo", "bar"], bullet="*", indent=3)
self.assertEqual(self.r.data, [" * foo bar"])
def test_field_simple(self):
self.r.field("fname", "fvalue")
self.assertEqual(self.r.data, [":fname: fvalue"])
def test_field_long_simple(self):
self.r.field("fname is fname", "fvalue")
self.assertEqual(self.r.data, [":fname is fname: fvalue"])
def test_field_simple_long(self):
self.r.field("fname", "v" * 54)
self.assertEqual(self.r.data, [":fname: " + "v" * 54])
def test_field_simple_long_long(self):
self.r.field("fname", "v" * 55)
self.assertEqual(self.r.data, [":fname:", "", " " + "v" * 55])
def test_field_indent_simple(self):
self.r.field("fname", "fvalue", indent=3)
self.assertEqual(self.r.data, [" :fname: fvalue"])
def test_field_indent_long_simple(self):
self.r.field("fname is fname", "fvalue", indent=3)
self.assertEqual(self.r.data, [" :fname is fname: fvalue"])
def test_field_indent_simple_long(self):
self.r.field("fname", "v" * 54, indent=3)
self.assertEqual(self.r.data, [" :fname: " + "v" * 54])
def test_field_indent_simple_long_long(self):
self.r.field("fname", "v" * 55, indent=3)
self.assertEqual(self.r.data,
[" :fname:", " ", " " + "v" * 55])
def test_field_wrap_simple(self):
self.r.field("fname", "the " * 100)
self.assertEqual(
self.r.data,
[
":fname:",
"",
" " + " the" * 18,
" " + " the" * 18,
" " + " the" * 18,
" " + " the" * 18,
" " + " the" * 18,
" " + " the" * 10,
],
)
def test_field_wrap_indent_simple(self):
self.r.field("fname", "the " * 100, indent=3)
self.assertEqual(
self.r.data,
[
" :fname:",
" ",
" " + " the" * 18,
" " + " the" * 18,
" " + " the" * 18,
" " + " the" * 18,
" " + " the" * 18,
" " + " the" * 10,
],
)
def test_content_string(self):
self.r.content("this is sparta")
self.assertEqual(self.r.data, ["this is sparta"])
def test_content_list(self):
self.r.content(["this is sparta", "this is spinal tap"])
self.assertEqual(self.r.data, ["this is sparta", "this is spinal tap"])
def test_content_indent_string(self):
self.r.content("this is sparta", indent=3)
self.assertEqual(self.r.data, [" this is sparta"])
def test_content_indent_list(self):
self.r.content(["this is sparta", "this is spinal tap"], indent=3)
self.assertEqual(self.r.data,
[" this is sparta", " this is spinal tap"])
def test_content_long(self):
self.r.content("the " * 100)
self.assertEqual(
self.r.data,
[
"the" + " the" * 17,
"the " * 17 + "the",
"the " * 17 + "the",
"the " * 17 + "the",
"the " * 17 + "the",
"the " * 9 + "the",
],
)
def test_ontent_indent_long(self):
self.r.content("the " * 100, indent=3)
self.assertEqual(
self.r.data,
[
" the" + " the" * 17,
" " + "the " * 17 + "the",
" " + "the " * 17 + "the",
" " + "the " * 17 + "the",
" " + "the " * 17 + "the",
" " + "the " * 9 + "the",
],
)
def test_ontent_indent_long_nowrap(self):
self.r.content("the " * 100, wrap=False, indent=3)
self.assertEqual(self.r.data, [" " + "the " * 99 + "the"])
def test_ref_target_named(self):
self.r.ref_target(name="foo-are-magic-ref0")
self.assertEqual(self.r.data, [".. _foo-are-magic-ref0:"])
def test_ref_target_unnamed(self):
self.r.ref_target("foo-are-magic-ref1")
self.assertEqual(self.r.data, [".. _foo-are-magic-ref1:"])
def test_ref_target_named_with_indent(self):
self.r.ref_target(name="foo-are-magic-ref2", indent=3)
self.assertEqual(self.r.data, [" .. _foo-are-magic-ref2:"])
def test_ref_target_unnamed_wo_indent(self):
self.r.ref_target("foo-are-magic-ref3", 3)
self.assertEqual(self.r.data, [" .. _foo-are-magic-ref3:"])
def test_set_data(self):
with self.assertRaises(AttributeError) as exception:
self.r.data = []
self.assertIn("cannot set the RstCloth.data attribute directly",
exception.exception.args)
class CustomTocTree(object):
def __init__(self, filename, sort=False):
self.spec = self._process_spec(filename, sort)
self.table = None
self.contents = None
self.dfn = None
def build_table(self):
self.table = tb.TableData()
self.table.add_header(['Name', 'Description'])
def build_dfn(self):
self.dfn = RstCloth()
def build_contents(self):
self.contents = RstCloth()
self.contents.directive('class', 'hidden')
self.contents.newline()
self.contents.directive('toctree',
fields=[('titlesonly', '')],
indent=3)
self.contents.newline()
def _process_spec(self, spec, sort=False):
o = []
with open(spec, 'r') as f:
data = yaml.load_all(f)
for datum in data:
if datum['description'] is None:
datum['description'] = ''
if sort is False:
pass
elif 'name' not in datum:
sort = False
o.append(datum)
if sort is True:
o.sort(key=lambda o: o['name'])
return o
def finalize(self):
for ref in self.spec:
if self.table is not None:
self.table.add_row([ref['name'], ref['description']])
if self.contents is not None:
self.contents.content(ref['file'], 6, block='toc')
if self.dfn is not None:
if 'name' in ref:
text = ref['name']
else:
text = None
link = self.dfn.role('doc', ref['file'], text)
self.dfn.definition(link, ref['description'], bold=False)
self.dfn.newline()