view document_it.py @ 20:7299c4529b41

more improvements
author Jeff Hammel <jhammel@mozilla.com>
date Tue, 02 Aug 2011 21:34:59 -0700
parents 493683e17eae
children 67e4becc7d49
line wrap: on
line source

#!/usr/bin/env python

"""
update MDN documentation from markdown

see:
http://developer.mindtouch.com/en/ref/MindTouch_API/POST%3Apages%2F%2F%7Bpageid%7D%2F%2Fcontents

The manifest format is in the form:

mozrunner/README.txt  https://developer.mozilla.org/en/Mozrunner
jsbridge/README.txt   https://developer.mozilla.org/en/JSbridge
mozmill/README.txt    https://developer.mozilla.org/en/Mozmill
mozmill/docs/         https://developer.mozilla.org/en/Mozmill/

--dest sets the destination, e.g.

--dest http://developer.mozilla.org/
--dest https://developer-stage9.mozilla.org/jhammel
--dest path/to directory

By default, a new temporary directory will be created
"""

import optparse
import os
import sys
import tempfile
import urllib2

# necessary imports
try:
    import markdown
except ImportError:
    raise ImportError("markdown is not installed, run (e.g.):\neasy_install Markdown")

DIR=os.path.dirname(os.path.abspath(__file__)) # XXX currently unused

def find_readme(directory):
    """find a README file in a directory"""
    # XXX currently unused
    README=['README.md', 'README.txt', 'README']
    for name in README:
        path = os.path.join(directory, name)
        if os.path.exists(path):
            return path

def all_files(directory):
    filenames = []
    for dirpath, dirnames, files in os.walk(directory):
        filenames.extend([os.path.join(dirpath, f) for f in files])
    return sorted(filenames)
                    
def parse_manifest(filename, baseurl, directory=None):
    """
    reads a documentation manifest; returns a list of two-tuples:
    [(filename, destination)]
    """
    
    assert os.path.exists(filename) and os.path.isfile(filename), "%s not found" % filename
    
    if directory is None:
        directory = os.path.dirname(os.path.abspath(filename))
    lines = [line.strip() for line in file(filename).readlines()]
    lines = [line for line in lines
             if line and not line.startswith('#')]
    items = []
    baseurl = baseurl.rstrip('/')
    for line in lines:
        try:
            f, url = line.split()
            # TODO: include options as third segment (e.g. format=ReST)
        except ValueError:
            raise ValueError("illegal manifest line: '%s'" % line)

        if '://' not in url:
            url = '%s%s' % (baseurl, url)
        filename = os.path.join(directory, f)
        if os.path.isdir(filename):
            files = all_files(filename)
            for i in files:
                relpath = os.path.relpath(i, filename)
                items.append((i, '%s%s' % (url.rstrip('/'), relpath.lstrip('/'))))
        else:
            items.append((filename, url))
    return items

def main(args=sys.argv[1:]):

    # default output directory
    default_dir = tempfile.mktemp()

    # parse command line options
    usage = '%prog [options] manifest <manifest> <...>'

    # description formatter
    class PlainDescriptionFormatter(optparse.IndentedHelpFormatter):
        def format_description(self, description):
            if description:
                return description.strip() + '\n'
            else:
                return ''
    
    parser = optparse.OptionParser(usage=usage, description=__doc__, formatter=PlainDescriptionFormatter())
    parser.add_option('-d', '--directory', dest='directory',
                      help='render the documentation from this directory')
    parser.add_option('-o', '--dest', dest='dest',
                      default=default_dir,
                      help='base directory or URL of destination [DEFAULT: %default]')
    parser.add_option('-u', '--user', dest='user',
                      help='user name')
    parser.add_option('-p', '--password', dest='password',
                      help='user password')
    parser.add_option('--list', dest='list', action='store_true', default=False,
                      help="list files")
    parser.add_option('--validate', dest='validate', # TODO unused
                      action='store_true', default=False,
                      help="validate the rendering but don't output")
    options, manifests = parser.parse_args(args)

    # print help if no manifests given
    if not args:
        parser.print_help()
        parser.exit()

    # get base url
    assert options.dest
    if '://' in options.dest:
        baseurl = options.dest
    else:
        baseurl = 'file://' + os.path.abspath(options.dest)

    # read the manifests
    files = []
    for manifest in manifests:
        for item in parse_manifest(manifest, baseurl, options.directory):
            if item not in files:
                files.append(item)
    if options.list:
        for item in files:
            print '%s -> %s' % item
        return

    if not files:
        return # you're done

    # render and upload READMEs
    if baseurl.startswith('file://'):
        options.dest = baseurl[len('file://'):] # deals with --dest file:///foo from command line

        # ensure a directory
        if os.path.exists(options.dest):
            assert os.path.isdir(options.dest), "'%s' - not a directory" % options.dest

        # TODO render to directory
        for src, dest in files:
            
            if dest.startswith('file://'):
                dest = dest[len('file://'):]

            # create a directory if needed
            dirname = os.path.dirname(dest)
            if os.path.exists(dirname):
                if not os.path.isdir(dirname):
                    # deal with filesystem directories vs PATH_INFO
                    f = file(dirname)
                    buffer = f.read()
                    f.close()
                    os.remove(dirname)
                    os.makedirs(dirname)
                    f = file(os.path.join(dirname, 'index.html'), 'w')
                    f.write(buffer)
                    f.close()
            else:
                os.makedirs(dirname)

            # render
            f = file(dest, 'w')
            buffer = markdown.Markdown().convert(file(src).read())
            f.write(buffer)
            f.close()
    else:
        # check credentials
        assert options.user and options.password, "Please supply your --user and --password"

        # upload the files
        # XXX just use curl for now
        import subprocess
        for src, dest in files:
            dest += '/contents?edittime=now'
            print src, dest
    
    if options.dest == default_dir:
        print "Files rendered to\n%s" % default_dir

if __name__ == '__main__':
    main()