From ca6e49360be1b7d25b0ff4c11473063ffc05f1e7 Mon Sep 17 00:00:00 2001
From: Ned Batchelder <ned@nedbatchelder.com>
Date: Tue, 26 May 2009 23:41:24 -0400
Subject: First successful coversion .rst -> .px -> .html

---
 doc/Makefile          |  4 ++++
 doc/_ext/px_xlator.py | 35 +++++++++++++++++++++++++----------
 doc/api.rst           | 24 ++++++++++++++++++++++++
 doc/index.rst         | 12 +-----------
 4 files changed, 54 insertions(+), 21 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index 5be97aa6..a820e372 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -35,6 +35,10 @@ px:
 	@echo
 	@echo "Build finished. The HTML pages are in _build/px."
 
+publish:
+	cp _build/px/*.px c:/ned/web/stellated/pages/code/coverage
+	cp sample_html/*.* c:/ned/web/stellated/pages/code/coverage/sample_html
+
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
 	@echo
diff --git a/doc/_ext/px_xlator.py b/doc/_ext/px_xlator.py
index 65cb7610..7bc3d69a 100644
--- a/doc/_ext/px_xlator.py
+++ b/doc/_ext/px_xlator.py
@@ -6,25 +6,32 @@ def setup(app):
     app.add_builder(PxBuilder)
 
 
-class PxTranslator(SmartyPantsHTMLTranslator):
+BaseHtmlXlator = SmartyPantsHTMLTranslator
+class PxTranslator(BaseHtmlXlator):
     """Adjust the HTML translator into a .px translator.
     
     """
 
     def __init__(self, *args, **kwargs):
-        SmartyPantsHTMLTranslator.__init__(self, *args, **kwargs)
+        BaseHtmlXlator.__init__(self, *args, **kwargs)
         #self.document.reporter.debug_flag = 1
-        
+        # To make the doc title be h0 (skipped), and the next h1.
+        self.initial_header_level = 0
+
     def visit_section(self, node):
         self.section_level += 1
 
     def depart_section(self, node):
         self.section_level -= 1
 
+    def visit_title(self, node):
+        if self.section_level == 1:
+            raise nodes.SkipNode
+        else:
+            BaseHtmlXlator.visit_title(self, node)
 
     # TODO: get history from here?
     def visit_field_list(self, node):
-        #self.document.reporter.debug_flag = 1;      # This should go somewhere else.
         raise nodes.SkipNode
 
     def depart_field_list(self, node):      pass
@@ -35,14 +42,10 @@ class PxTranslator(SmartyPantsHTMLTranslator):
     def visit_field_body(self, node):       pass
     def depart_field_body(self, node):      pass
 
-    def xx_visit_Text(self, node):
-        self.body.append("XX")
-        SmartyPantsHTMLTranslator.visit_Text(self, node)
-
     def visit_literal_block(self, node):
         if node.rawsource != node.astext():
             # most probably a parsed-literal block -- don't highlight
-            return BaseTranslator.visit_literal_block(self, node)
+            return BaseHtmlXlator.visit_literal_block(self, node)
         lang = self.highlightlang
         if node.has_key('language'):
             # code-block directives
@@ -51,7 +54,14 @@ class PxTranslator(SmartyPantsHTMLTranslator):
         self.body.append(self.encode(node.rawsource))
         self.body.append('</code>\n')
         raise nodes.SkipNode
-        
+
+    def visit_desc_parameterlist(self, node):
+        self.body.append('(')
+        self.first_param = 1
+    def depart_desc_parameterlist(self, node):
+        self.body.append(')')
+
+
 class PxBuilder(StandaloneHTMLBuilder):
     name = 'px'
 
@@ -63,3 +73,8 @@ class PxBuilder(StandaloneHTMLBuilder):
         
         self.out_suffix = '.px'
         self.link_suffix = '.html'
+        
+        self.px_uri = "/code/coverage/"
+
+    def get_target_uri(self, docname, typ=None):
+        return self.px_uri + docname + self.link_suffix
diff --git a/doc/api.rst b/doc/api.rst
index 285ca3d1..279e9dbb 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -4,6 +4,30 @@
 Coverage API
 ============
 
+The API to coverage.py is very simple, contained in a single module called
+coverage containing a single class, also called coverage::
+    
+    import coverage
+
+    cov = coverage.coverage()
+    
+Methods on the coverage object correspond to operations available in the
+command line interface.  For example, a simple use would be::
+
+    import coverage
+    
+    cov = coverage.coverage()
+    cov.start()
+    
+    # .. run your code ..
+    
+    cov.stop()
+    cov.save()
+
+
+The coverage module
+-------------------
+
 .. module:: coverage
 
 .. autoclass:: coverage
diff --git a/doc/index.rst b/doc/index.rst
index 68472c2a..87098326 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -61,17 +61,7 @@ Getting started with coverage.py is easy:
         $ coverage -b -i -d htmlcov
 
     Then visit htmlcov/index.html in your browser, to see a
-    `report like this <sample_html/index.html>`_.
-
-Getting Help
-~~~~~~~~~~~~
-
-This is a third-level section, with some XML:
-
-.. code-block:: xml
-
-    <tag attr='value'>1 &lt; 2 &amp 2 &gt; 1</tag>
-    Whoa!
+    `report like this </code/coverage/sample_html/index.html>`_.
 
 
 Using coverage.py
-- 
cgit v1.2.1