Browse Source

Implement fenced sections

develop
Sven Slootweg 8 years ago
parent
commit
0fbcbaf6d3
  1. 2
      setup.py
  2. 20
      site/documentation.zpy
  3. 4
      src/zippydoc/block_markup.py
  4. 30
      src/zippydoc/data/template.html
  5. 4
      src/zippydoc/document.py
  6. 3
      src/zippydoc/transformation_ruleset.py
  7. 3
      zpy2html

2
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.',

20
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

4
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):

30
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
{

4
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("$ ")

3
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

3
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)

Loading…
Cancel
Save