From 0fbcbaf6d3c34ace86b5f0dd39c168a21f186c8f Mon Sep 17 00:00:00 2001
From: Sven Slootweg <jamsoftgamedev@gmail.com>
Date: Wed, 22 Jan 2014 09:05:18 +0100
Subject: [PATCH] Implement fenced sections

---
 setup.py                               |  2 +-
 site/documentation.zpy                 | 20 +++++++++++++++++
 src/zippydoc/block_markup.py           |  4 ++++
 src/zippydoc/data/template.html        | 30 +++++++++++++++++++++++---
 src/zippydoc/document.py               |  4 ++++
 src/zippydoc/transformation_ruleset.py |  3 +++
 zpy2html                               |  3 +++
 7 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/setup.py b/setup.py
index c6856cf..cc8f718 100644
--- a/setup.py
+++ b/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.',
diff --git a/site/documentation.zpy b/site/documentation.zpy
index 79f9440..984433d 100644
--- a/site/documentation.zpy
+++ b/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
diff --git a/src/zippydoc/block_markup.py b/src/zippydoc/block_markup.py
index d3282ce..ce85571 100644
--- a/src/zippydoc/block_markup.py
+++ b/src/zippydoc/block_markup.py
@@ -75,6 +75,10 @@ class Argument(TreeLevel):
 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):
diff --git a/src/zippydoc/data/template.html b/src/zippydoc/data/template.html
index d8ea410..9efb73c 100644
--- a/src/zippydoc/data/template.html
+++ b/src/zippydoc/data/template.html
@@ -22,20 +22,44 @@
 				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;
+			}
+			
+			.section
+			{
+				background-color: #E8E8E8; 
+			}
+			
+			.section > .title
+			{
+				font-size: 16px;
 			}
 
-			.example > .children
+			.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
 			{
diff --git a/src/zippydoc/document.py b/src/zippydoc/document.py
index 7aa47e8..af198f0 100644
--- a/src/zippydoc/document.py
+++ b/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("$ ")
diff --git a/src/zippydoc/transformation_ruleset.py b/src/zippydoc/transformation_ruleset.py
index a916e4c..4b963f9 100644
--- a/src/zippydoc/transformation_ruleset.py
+++ b/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
 		
diff --git a/zpy2html b/zpy2html
index be61534..2d65791 100755
--- a/zpy2html
+++ b/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)