view document_it.py @ 12:54e27f046cd2

more stubbing
author Jeff Hammel <jhammel@mozilla.com>
date Tue, 02 Aug 2011 16:06:29 -0700
parents df6c2e71b87e
children 1efb669ab1c8
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 parse_manifest(filename, 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 = []
    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)

        url = url.lstrip('/') # no leading /s
        filename = os.path.join(directory, f)
        if os.path.isdir(filename):
            pass # TODO
        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 + '\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('--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('--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://' + options.dest

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

    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:
            dest = os.path.join(options.dest, dest)

            # create a directory if needed
            dirname = os.path.dirname(dest)
            os.makedirs(dirname)

            # render
            f = file(dest, 'w')
            buffer = markdown.Markdown().convert(file(src).read())
            f.write(buffer)
            f.close()
    else:
        # TODO check credentials
        for src, dest in files:
            pass
        raise NotImplementedError

    
    if options.dest == default_dir:
        print "Files rendered to\n%s" % default_dir

if __name__ == '__main__':
    main()