Implement fenced sections

setup.py

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

site/documentation.zpy

@@ -44,6 +44,26 @@ starting a new block.
 			
 		$$	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
 
 	An argument block shows a particular argument or parameter, and its explanation. The argument name is suffixed with a double colon (::), and the explanation

src/zippydoc/block_markup.py

@@ -76,6 +76,10 @@ class Example(TreeLevel):
 	def transform(self, 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):
 	def transform(self, ruleset):
 		return ruleset.transform_code(self.data)

src/zippydoc/data/template.html

@@ -22,21 +22,45 @@
 				margin-bottom: 32px;
 			}
 
-			.example 
+			.example , .section
 			{ 
 				padding: 5px 6px;
 				font-weight: bold;
+				margin-top: 11px;
+			}
+			
+			.example
+			{
 				font-size: 15px;
 				background-color: #E6E6E6; 
-				margin-top: 11px;
 			}
 			
-			.example > .children
+			.section
+			{
+				background-color: #E8E8E8; 
+			}
+			
+			.section > .title
+			{
+				font-size: 16px;
+			}
+
+			.example > .children, .section > .children
 			{
 				padding-top: 11px;
 				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
 			{
 				font-size: 13px;

src/zippydoc/document.py

@@ -43,6 +43,10 @@ class Document(object):
 				# Example
 				lines[0] = lines[0].lstrip("@ ")
 				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":
 				# Code continuation
 				self.current_elements[current_level].data += "\n\n" + "\n".join(lines).lstrip("$ ")

src/zippydoc/transformation_ruleset.py

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

zpy2html

@@ -49,6 +49,9 @@ class HtmlRuleset(zippydoc.TransformationRuleset):
 	def transform_example(self, title, 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):
 		return '<h7>Code:</h7><pre class="code">%s</pre>' % self.escape_html(text)