reST support

pycco/main.py

@@ -6,8 +6,9 @@
 documentation generator. It produces HTML that displays your comments
 alongside your code. Comments are passed through
 [Markdown](http://daringfireball.net/projects/markdown/syntax) and
-[SmartyPants](http://daringfireball.net/projects/smartypants), while code is
-passed through [Pygments](http://pygments.org/) for syntax highlighting.
+[SmartyPants](http://daringfireball.net/projects/smartypants) or either
+[reST](http://docutils.sourceforge.net/rst.html). Code is passed through
+[Pygments](http://pygments.org/) for syntax highlighting.
 This page is the result of running Pycco against its own source file.
 
 If you install Pycco, you can run it from the command-line:
@@ -33,7 +34,7 @@
 
 # === Main Documentation Generation Functions ===
 
-def generate_documentation(source, outdir=None, preserve_paths=True):
+def generate_documentation(source, outdir=None, preserve_paths=True, syntax=None):
     """
     Generate the documentation for a source file by reading it in, splitting it
     up into comment/code sections, highlighting them for the appropriate
@@ -44,7 +45,7 @@ def generate_documentation(source, outdir=None, preserve_paths=True):
         raise TypeError("Missing the required 'outdir' keyword argument.")
     fh = open(source, "r")
     sections = parse(source, fh.read())
-    highlight(source, sections, preserve_paths=preserve_paths, outdir=outdir)
+    highlight(source, sections, preserve_paths=preserve_paths, outdir=outdir, syntax=syntax)
     return generate_html(source, sections, preserve_paths=preserve_paths, outdir=outdir)
 
 def parse(source, code):
@@ -189,10 +190,10 @@ def replace_section_name(match):
 
 # === Highlighting the source code ===
 
-def highlight(source, sections, preserve_paths=True, outdir=None):
+def highlight(source, sections, preserve_paths=True, outdir=None, syntax=None):
     """
     Highlights a single chunk of code using the **Pygments** module, and runs
-    the text of its corresponding comment through **Markdown**.
+    the text of its corresponding comment through **Markdown** or **reST**.
 
     We process the entire file in a single call to Pygments by inserting little
     marker comments between each section and then splitting the result string
@@ -215,10 +216,10 @@ def highlight(source, sections, preserve_paths=True, outdir=None):
             docs_text = unicode(section["docs_text"])
         except UnicodeError:
             docs_text = unicode(section["docs_text"].decode('utf-8'))
-        section["docs_html"] = markdown(preprocess(docs_text,
-                                                   i,
-                                                   preserve_paths=preserve_paths,
-                                                   outdir=outdir))
+        section["docs_html"] = SYNTAX_FUNC(preprocess(docs_text,
+                                                      i,
+                                                      preserve_paths=preserve_paths,
+                                                      outdir=outdir))
         section["num"] = i
 
 # === HTML Code generation ===
@@ -272,6 +273,10 @@ def generate_html(source, sections, preserve_paths=True, outdir=None):
 from os import path
 from pygments import lexers, formatters
 
+
+SYNTAX_FUNC = markdown  # Used for parsing docstrings and comments
+
+
 # A list of the languages that Pycco supports, mapping the file extension to
 # the name of the Pygments lexer and the symbol that indicates a comment. To
 # add another language to Pycco's repertoire, add it here.
@@ -387,7 +392,7 @@ def template(source):
 # The end of each Pygments highlight block.
 highlight_end = "</pre></div>"
 
-def process(sources, preserve_paths=True, outdir=None):
+def process(sources, preserve_paths=True, outdir=None, syntax=None):
     """For each source file passed as argument, generate the documentation."""
 
     if not outdir:
@@ -414,7 +419,7 @@ def next_file():
                 pass
 
             with open(dest, "w") as f:
-                f.write(generate_documentation(s, preserve_paths=preserve_paths, outdir=outdir))
+                f.write(generate_documentation(s, preserve_paths=preserve_paths, outdir=outdir, syntax=syntax))
 
             print "pycco = %s -> %s" % (s, dest)
 
@@ -471,7 +476,12 @@ def on_modified(self, event):
 def main():
     """Hook spot for the console script."""
 
+    global SYNTAX_FUNC
+
     parser = optparse.OptionParser()
+    parser.add_option('-s', '--syntax', action='store', choices=['markdown', 'reST'],
+                      help='Specify markup language: markdown, reST', default='markdown')
+
     parser.add_option('-p', '--paths', action='store_true',
                       help='Preserve path structure of original files')
 
@@ -483,7 +493,14 @@ def main():
                       help='Watch original files and re-generate documentation on changes')
     opts, sources = parser.parse_args()
 
-    process(sources, outdir=opts.outdir, preserve_paths=opts.paths)
+    if opts.syntax == 'reST':
+        try:
+            from creole.rest2html.clean_writer import rest2html
+        except ImportError:
+            sys.exit('The -s reST option requires the python-creole package.')
+        SYNTAX_FUNC = rest2html
+
+    process(sources, outdir=opts.outdir, preserve_paths=opts.paths, syntax=opts.syntax)
 
     # If the -w / --watch option was present, monitor the source directories
     # for changes and re-generate documentation for source files whenever they
@@ -497,6 +514,7 @@ def main():
 
         monitor(sources, opts)
 
+
 # Run the script.
 if __name__ == "__main__":
     main()

setup.py

@@ -16,5 +16,5 @@
                 ]
             },
         install_requires = ['markdown', 'pygments', 'pystache', 'smartypants'],
-        extras_require = {'monitoring': 'watchdog'},
+        extras_require = {'monitoring': 'watchdog', 'reST': 'python-creole'},
         )