Added documentation for the table of contents to the userguide.
authorjonas
Thu, 15 Jan 2009 16:59:35 +0000
changeset 3059 3a6ff201e927
parent 3058 7f508fe1227c
child 3060 eeedb611fa67
Added documentation for the table of contents to the userguide.
docs/userguide/ch1_intro.py
docs/userguide/ch6_tables.py
docs/userguide/ch9_future.py
docs/userguide/genuserguide.py
tests/test_platypus_toc.py
tools/docco/rl_doc_utils.py
--- a/docs/userguide/ch1_intro.py	Thu Jan 15 10:34:53 2009 +0000
+++ b/docs/userguide/ch1_intro.py	Thu Jan 15 16:59:35 2009 +0000
@@ -11,20 +11,17 @@
 
 nextTemplate("TOC")
 
-tableofcontents()
+headingTOC()
 
+toc = TableOfContents()
 PS = ParagraphStyle
-tocstyles = [
+toc.levelStyles = [
     PS(fontName='Times-Bold', fontSize=14, name='TOCHeading1', leftIndent=20, firstLineIndent=-20, spaceBefore=5, leading=16),
     PS(fontSize=12, name='TOCHeading2', leftIndent=40, firstLineIndent=-20, spaceBefore=0, leading=12),
     PS(fontSize=10, name='TOCHeading3', leftIndent=60, firstLineIndent=-20, spaceBefore=0, leading=12),
     PS(fontSize=10, name='TOCHeading4', leftIndent=100, firstLineIndent=-20, spaceBefore=0, leading=12),
 ]
-
-story = getStory()
-toc = TableOfContents()
-toc.levelStyles = tocstyles
-story.append(toc)
+getStory().append(toc)
 
 nextTemplate("Normal")
 
--- a/docs/userguide/ch6_tables.py	Thu Jan 15 10:34:53 2009 +0000
+++ b/docs/userguide/ch6_tables.py	Thu Jan 15 16:59:35 2009 +0000
@@ -415,3 +415,112 @@
 If the total height of the $Flowables$ in the list $flowables$ exceeds the current frame's available
 space then all the space is used and a frame break is forced.
 """)
+CPage(1)
+heading2("""$TableOfContents()$""")
+disc("""
+A table of contents can be generated by using the $TableOfContents$ flowable.
+
+The following steps are needed to add a table of contents to your document:
+""")
+
+disc("""Create an instance of $TableOfContents$. Override the level styles (optional) and add the object to the story:""")
+
+eg("""
+toc = TableOfContents()
+PS = ParagraphStyle
+toc.levelStyles = [
+    PS(fontName='Times-Bold', fontSize=14, name='TOCHeading1',
+            leftIndent=20, firstLineIndent=-20, spaceBefore=5, leading=16),
+    PS(fontSize=12, name='TOCHeading2',
+            leftIndent=40, firstLineIndent=-20, spaceBefore=0, leading=12),
+    PS(fontSize=10, name='TOCHeading3',
+            leftIndent=60, firstLineIndent=-20, spaceBefore=0, leading=12),
+    PS(fontSize=10, name='TOCHeading4',
+            leftIndent=100, firstLineIndent=-20, spaceBefore=0, leading=12),
+]
+story.append(toc)
+""")
+
+disc("""Entries to the table of contents can be done either manually by calling the $addEntry$ method on the $TableOfContents$ object
+or automatically by sending a $'TOCEntry'$ notification in the $afterFlowable$ method of the $DocTemplate$ you are using:""")
+
+eg('''
+def afterFlowable(self, flowable):
+    """Detect Level 1 and 2 headings, build outline,
+    and track chapter title."""
+    if isinstance(flowable, Paragraph):
+        txt = flowable.getPlainText()
+        if style == 'Heading1':
+            # ...
+            self.notify('TOCEntry', (0, txt, self.page))
+        elif style == 'Heading2':
+            # ...
+            self.notify('TOCEntry', (1, txt, self.page))
+        # ...
+''')
+
+disc("""This way, whenever a paragraph of style $'Heading1'$ or $'Heading2'$ is added to the story, it will appear in the table of contents.""")
+
+disc("""Finally you need to use the $multiBuild$ method of the DocTemplate because tables of contents need several passes to be generated:""")
+
+eg("""
+doc.multiBuild(story)
+""")
+
+disc("""Below is a simple but working example of a document with a table of contents:""")
+
+eg('''
+from reportlab.lib.styles import ParagraphStyle as PS
+from reportlab.platypus import PageBreak
+from reportlab.platypus.paragraph import Paragraph
+from reportlab.platypus.doctemplate import PageTemplate, BaseDocTemplate
+from reportlab.platypus.tableofcontents import TableOfContents
+from reportlab.platypus.frames import Frame
+from reportlab.lib.units import cm
+
+class MyDocTemplate(BaseDocTemplate):
+
+    def __init__(self, filename, **kw):
+        self.allowSplitting = 0
+        apply(BaseDocTemplate.__init__, (self, filename), kw)
+        template = PageTemplate('normal', [Frame(2.5*cm, 2.5*cm, 15*cm, 25*cm, id='F1')])
+        self.addPageTemplates(template)
+
+    def afterFlowable(self, flowable):
+        "Registers TOC entries."
+        if flowable.__class__.__name__ == 'Paragraph':
+            text = flowable.getPlainText()
+            style = flowable.style.name
+            if style == 'Heading1':
+                self.notify('TOCEntry', (0, text, self.page))
+            if style == 'Heading2':
+                self.notify('TOCEntry', (1, text, self.page))
+
+h1 = PS(name = 'Heading1',
+       fontSize = 14,
+       leading = 16)
+
+h2 = PS(name = 'Heading2',
+       fontSize = 12,
+       leading = 14,
+       leftIndent = delta)
+
+# Build story.
+story = []
+toc = TableOfContents()
+# For conciseness we use the same styles for headings and TOC entries
+toc.levelStyles = [h1, h2]
+story.append(toc)
+story.append(PageBreak())
+story.append(Paragraph('First heading', h1))
+story.append(Paragraph('Text in first heading', PS('body')))
+story.append(Paragraph('First sub heading', h2))
+story.append(Paragraph('Text in first sub heading', PS('body')))
+story.append(PageBreak())
+story.append(Paragraph('Second sub heading', h2))
+story.append(Paragraph('Text in second sub heading', PS('body')))
+story.append(Paragraph('Last heading', h1))
+
+doc = MyDocTemplate('mintoc.pdf')
+doc.multiBuild(story)
+''')
--- a/docs/userguide/ch9_future.py	Thu Jan 15 10:34:53 2009 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,35 +0,0 @@
-#Copyright ReportLab Europe Ltd. 2000-2004
-#see license.txt for license details
-#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/userguide/ch9_future.py
-from tools.docco.rl_doc_utils import *
-
-heading1("Future Directions")
-
-disc("""We have a very long list of things we plan to do
-and what we do first will most likely be inspired by customer
-or user interest.
-""")
-
-disc("""
-We plan to provide a large number of pre-designed Platypus example
-document types -- brochure, newsletter, business letter, thesis, memo,
-etcetera, to give our users a better boost towards the solutions they
-desire.
-""")
-
-disc("""
-We plan to fully support adding fonts and internationalization, which are
-not well supported in the current release.""")
-
-disc("""
-We plan to fully support some of the more obscure features of PDF
-such as general hyperlinks, which are not yet well supported.
-""")
-
-disc("""
-We are also open for suggestions.  Please let us know what you think
-is missing.  You can also offer patches or contributions.  Please
-look to $http://www.reportlab.com$ for the latest mailing list and
-contact information.""")
-
-# this comment is a trivial test of SF checkin rights - delete it some time!  AR 2001-04-17
--- a/docs/userguide/genuserguide.py	Thu Jan 15 10:34:53 2009 +0000
+++ b/docs/userguide/genuserguide.py	Thu Jan 15 16:59:35 2009 +0000
@@ -7,24 +7,6 @@
 This module contains the script for building the user guide.
 """
 
-def makeTocHeaderStyle(level, delta, epsilon, fontName='Times-Roman'):
-    "Make a header style for different levels."
-
-    assert level >= 0, "Level must be >= 0."
-
-    PS = ParagraphStyle
-    size = 12
-    style = PS(name = 'Heading' + str(level),
-               fontName = fontName,
-               fontSize = size,
-               leading = size*1.2,
-               spaceBefore = size/4.0,
-               spaceAfter = size/8.0,
-               firstLineIndent = -epsilon,
-               leftIndent = level*delta + epsilon)
-
-    return style
-
 def run(pagesize=None, verbose=0, outDir=None):
     import sys,os
     from reportlab.lib.utils import open_and_read
@@ -61,7 +43,6 @@
         'ch5_paragraphs',
         'ch6_tables',
         'ch7_custom',
-        'ch9_future',
         'app_demos',
         ):
         exec open_and_read(f+'.py',mode='t') in G, G
--- a/tests/test_platypus_toc.py	Thu Jan 15 10:34:53 2009 +0000
+++ b/tests/test_platypus_toc.py	Thu Jan 15 16:59:35 2009 +0000
@@ -22,8 +22,6 @@
 from reportlab.platypus.doctemplate \
      import PageTemplate, BaseDocTemplate
 from reportlab.platypus import tableofcontents
-from reportlab.platypus.tableofcontents import TableOfContents
-from reportlab.platypus.tables import TableStyle, Table
 from reportlab.lib import randomtext
 
 
@@ -153,7 +151,7 @@
         description = '<font color=red>%s</font>' % self.test0.__doc__
         story.append(XPreformatted(description, bt))
 
-        toc = TableOfContents()
+        toc = tableofcontents.TableOfContents()
         toc.levelStyles = tocLevelStyles
         story.append(toc)
 
--- a/tools/docco/rl_doc_utils.py	Thu Jan 15 10:34:53 2009 +0000
+++ b/tools/docco/rl_doc_utils.py	Thu Jan 15 16:59:35 2009 +0000
@@ -165,7 +165,7 @@
 #AR 3/7/2000 - defining three new levels of headings; code
 #should be swapped over to using them.
 
-def tableofcontents(text='Table of contents'):
+def headingTOC(text='Table of contents'):
     getStory().append(PageBreak())
     p = Paragraph(text, H1)
     getStory().append(p)