Implement fenced sections

develop
Sven Slootweg 10 years ago
parent fc3f2c3e3c
commit 0fbcbaf6d3

@ -33,7 +33,7 @@ print repr(package_data)
setup( setup(
name='zippydoc', name='zippydoc',
version='1.1', version='1.2',
maintainer='Sven Slootweg', maintainer='Sven Slootweg',
maintainer_email='admin@cryto.net', maintainer_email='admin@cryto.net',
description='Documentation markup language and library, including HTML converter.', description='Documentation markup language and library, including HTML converter.',

@ -44,6 +44,26 @@ starting a new block.
$$ Some kind of text describing the function goes here. $$ Some kind of text describing the function goes here.
^ Fenced section
A fenced section is a section, intended for grouping together similar information. It is displayed in a "box" when outputting as HTML, and is mostly useful
for API and code documentation, where you would for example want to distinguish between arguments, return vales and exceptions, even if both use the
same "argument block" syntax (described below). To use a fenced section, you prefix the section title with an `=` (equals sign), and indent its children.
All child elements are treated like they normally would have been.
@ Using a fenced section
$ ^ my_function(**argument**, **another_argument**)
$$ = Arguments
$$ argument::
This is the first argument to this example function.
$$ another_argument::
This is the second argument to this example function.
As you can see, it's possible to split the explanation over multiple lines as well.
^ Argument block ^ Argument block
An argument block shows a particular argument or parameter, and its explanation. The argument name is suffixed with a double colon (::), and the explanation An argument block shows a particular argument or parameter, and its explanation. The argument name is suffixed with a double colon (::), and the explanation

@ -75,6 +75,10 @@ class Argument(TreeLevel):
class Example(TreeLevel): class Example(TreeLevel):
def transform(self, ruleset): def transform(self, ruleset):
return ruleset.transform_example(Value(self.data), self.transform_children(ruleset)) return ruleset.transform_example(Value(self.data), self.transform_children(ruleset))
class Section(TreeLevel):
def transform(self, ruleset):
return ruleset.transform_section(Value(self.data), self.transform_children(ruleset))
class Code(TreeLevel): class Code(TreeLevel):
def transform(self, ruleset): def transform(self, ruleset):

@ -22,20 +22,44 @@
margin-bottom: 32px; margin-bottom: 32px;
} }
.example .example , .section
{ {
padding: 5px 6px; padding: 5px 6px;
font-weight: bold; font-weight: bold;
margin-top: 11px;
}
.example
{
font-size: 15px; font-size: 15px;
background-color: #E6E6E6; background-color: #E6E6E6;
margin-top: 11px; }
.section
{
background-color: #E8E8E8;
}
.section > .title
{
font-size: 16px;
} }
.example > .children .example > .children, .section > .children
{ {
padding-top: 11px; padding-top: 11px;
padding-left: 10px; padding-left: 10px;
} }
.section > .children
{
font-size: 95%;
}
.section > .children > div.text:first-child, .section > .children > dl:first-child
{
margin-top: 0px;
}
.example > .children > h7 .example > .children > h7
{ {

@ -43,6 +43,10 @@ class Document(object):
# Example # Example
lines[0] = lines[0].lstrip("@ ") lines[0] = lines[0].lstrip("@ ")
element = block_markup.Example(indentation, " ".join(lines)) element = block_markup.Example(indentation, " ".join(lines))
elif lines[0].startswith("="):
# Fenced section
lines[0] = lines[0].lstrip("= ")
element = block_markup.Section(indentation, " ".join(lines))
elif lines[0].startswith("$$") and self.current_elements[current_level].__class__.__name__ == "Code": elif lines[0].startswith("$$") and self.current_elements[current_level].__class__.__name__ == "Code":
# Code continuation # Code continuation
self.current_elements[current_level].data += "\n\n" + "\n".join(lines).lstrip("$ ") self.current_elements[current_level].data += "\n\n" + "\n".join(lines).lstrip("$ ")

@ -14,6 +14,9 @@ class TransformationRuleset(object):
def transform_example(self, title, children): def transform_example(self, title, children):
pass pass
def transform_section(self, title, children):
pass
def transform_code(self, text): def transform_code(self, text):
pass pass

@ -49,6 +49,9 @@ class HtmlRuleset(zippydoc.TransformationRuleset):
def transform_example(self, title, children): def transform_example(self, title, children):
return '<div class="example">Example: %s %s</div>' % (title.transform(self), children) return '<div class="example">Example: %s %s</div>' % (title.transform(self), children)
def transform_section(self, title, children):
return '<div class="section"><div class="title">%s</div>%s</div>' % (title.transform(self), children)
def transform_code(self, text): def transform_code(self, text):
return '<h7>Code:</h7><pre class="code">%s</pre>' % self.escape_html(text) return '<h7>Code:</h7><pre class="code">%s</pre>' % self.escape_html(text)

Loading…
Cancel
Save