Ticket #528: render_docs.py.2.diff

extras/README.TXT

@@ -1 +1 @@
 This directory contains extra stuff that can improve your Django experience.
+
+
+render_docs.py
+
+This is a python script that generates html from your django documentation.
+It is run from the command line, and takes two arguments.
+
+$ python render_docs.py <source directory> <destination directory>
+
+Optionally, if you want it to generate one big page instead of multiple smaller
+ones, you can supply the --single argument.
+
+$ python render_docs.py --single <source directory> <destination directory>
+

new file extras/render_docs.py

@@ +1 @@
+#!/usr/bin/env python
+
+import optparse
+import os
+import re
+import sys
+
+try:
+    from docutils.core import publish_parts
+    from docutils.writers import html4css1
+except:
+    print "The python module docutils is required to run this script."
+    print "It doesn't seem like it is installed in your pythonpath."
+    sys.exit(1)
+
+def main():
+    # parse with command line
+    parser = optparse.OptionParser()
+    parser.add_option('-1', '--single', action="store_true", dest="single", default=False, help="Write one single combined doc instead of several.")
+    options, dirs = parser.parse_args()
+    if len(dirs) != 2:
+        print "Need exactly one source and one output directory."
+        sys.exit(1)
+    source, dest = dirs
+    
+    # find all docs in source dir
+    if options.single:
+        single = ""
+    files = [f for f in os.listdir(source) if f.endswith('.txt')]
+    files.sort()
+    docs = []
+    for doc in files:
+        out = doc[:-4] + ".html"
+        parts = publish_parts(open(os.path.join(source, doc)).read(), writer=html4css1.Writer(), settings_overrides={'initial_header_level': 2})
+    
+        # save filename and title for table of contents
+        try:
+            docs.append([out, parts['title']])
+        except IndexError:
+            docs.append([out, 'UNKNOWN (%s)' % doc])
+    
+        # append to single doc
+        if options.single:
+            single += '<a name="%s" />' % out
+            single += parts['html_body']
+        # write out the doc
+        else:
+            open(os.path.join(dest, out), 'w').write(parts['whole'].encode('utf-8'))
+    
+    # output toc/single doc
+    if options.single:
+        toc = "django.html"
+    else:
+        toc = "index.html"
+    output = open(os.path.join(dest, toc), 'w')
+    output.write(parts['html_prolog'] % 'utf-8')
+    output.write(parts['html_head'] % 'utf-8')
+    output.write('<title>Django Documentation</title></head></body>')
+    output.write('<h1>Table of Contents</h1><ul>')
+    for href, title in docs:
+        if options.single:
+            href = "#" + href
+        output.write('<li><a href="%s">%s</a></li>' % (href, title))
+    output.write('</ul>')
+    if options.single:
+        output.write(single.encode('utf-8'))
+    output.write('</body></html>')
+
+if __name__ == "__main__":
+    main()