impala/shell/ext-py/bitarray-2.3.0/update_doc.py

import sys
assert sys.version_info[0] == 3, "This program requires Python 3"

import re
import doctest
from io import StringIO

import bitarray
import bitarray.util


BASE_URL = "https://github.com/ilanschnell/bitarray"

NEW_IN = {
    'frozenbitarray':       '1.1',
    'get_default_endian':   '1.3',
    'util.make_endian':     '1.3',
    'bitarray':             '2.3: optional `buffer` argument',
    'bitarray.bytereverse': '2.2.5: optional `start` and `stop` arguments',
    'bitarray.count':       '1.1.0: optional `start` and `stop` arguments',
    'bitarray.clear':       '1.4',
    'bitarray.find':        '2.1',
    'bitarray.invert':      '1.5.3: optional `index` argument',
    'decodetree':           '1.6',
    'util.urandom':         '1.7',
    'util.pprint':          '1.8',
    'util.serialize':       '1.8',
    'util.deserialize':     '1.8',
    'util.ba2base':         '1.9',
    'util.base2ba':         '1.9',
    'util.parity':          '1.9',
    'util.rindex':          '2.3.0: optional `start` and `stop` arguments',
    'util.vl_encode':       '2.2',
    'util.vl_decode':       '2.2',
}

DOCS = {
    'rep': ('Bitarray representations', 'represent.rst'),
    'vlf': ('Variable length bitarray format', 'variable_length.rst'),
}

DOC_LINKS = {
    'util.ba2base':     'rep',
    'util.base2ba':     'rep',
    'util.serialize':   'rep',
    'util.deserialize': 'rep',
    'util.vl_encode':   'vlf',
    'util.vl_decode':   'vlf',
}

_NAMES = set()

sig_pat = re.compile(r'(\w+\([^()]*\))( -> (.+))?')
def write_doc(fo, name):
    _NAMES.add(name)
    doc = eval('bitarray.%s.__doc__' % name)
    assert doc, name
    lines = doc.splitlines()
    m = sig_pat.match(lines[0])
    if m is None:
        raise Exception("signature line invalid: %r" % lines[0])
    s = '``%s``' %  m.group(1)
    if m.group(3):
        s += ' -> %s' % m.group(3)
    fo.write('%s\n' % s)
    assert lines[1] == ''
    for line in lines[2:]:
        out = line.rstrip()
        fo.write("   %s\n" % out.replace('`', '``') if out else "\n")

    link = DOC_LINKS.get(name)
    if link:
        title, filename = DOCS[link]
        url = BASE_URL + '/blob/master/doc/' + filename
        fo.write("\n   See also: `%s <%s>`__\n" % (title, url))

    new_in = NEW_IN.get(name)
    if new_in:
        fo.write("\n   New in version %s.\n" % new_in.replace('`', '``'))

    fo.write('\n\n')


def write_reference(fo):
    fo.write("""\
Reference
=========

bitarray version: %s -- `change log <%s>`__

In the following, ``item`` and ``value`` are usually a single bit -
an integer 0 or 1.


The bitarray object:
--------------------

""" % (bitarray.__version__, BASE_URL + "/blob/master/doc/changelog.rst"))
    write_doc(fo, 'bitarray')

    fo.write("**A bitarray object supports the following methods:**\n\n")
    for method in sorted(dir(bitarray.bitarray)):
        if method.startswith('_'):
            continue
        write_doc(fo, 'bitarray.%s' % method)

    fo.write("Other objects:\n"
             "--------------\n\n")
    write_doc(fo, 'frozenbitarray')
    write_doc(fo, 'decodetree')

    fo.write("Functions defined in the `bitarray` module:\n"
             "-------------------------------------------\n\n")
    for func in sorted(['test', 'bits2bytes', 'get_default_endian']):
        write_doc(fo, func)

    fo.write("Functions defined in `bitarray.util` module:\n"
             "--------------------------------------------\n\n"
             "This sub-module was add in version 1.2.\n\n")
    for func in bitarray.util.__all__:
        write_doc(fo, 'util.%s' % func)

    for name in list(NEW_IN) + list(DOC_LINKS):
        assert name in _NAMES, name

def update_readme(path):
    ver_pat = re.compile(r'(bitarray.+?)(\d+\.\d+\.\d+)')

    with open(path, 'r') as fi:
        data = fi.read()

    with StringIO() as fo:
        for line in data.splitlines():
            if line == 'Reference':
                break
            line = ver_pat.sub(lambda m: m.group(1) + bitarray.__version__,
                               line)
            fo.write("%s\n" % line.rstrip())

        write_reference(fo)
        new_data = fo.getvalue()

    if new_data == data:
        print("already up-to-date")
    else:
        with open(path, 'w') as f:
            f.write(new_data)


def write_changelog(fo):
    ver_pat = re.compile(r'(\d{4}-\d{2}-\d{2})\s+(\d+\.\d+\.\d+)')
    issue_pat = re.compile(r'#(\d+)')
    link_pat = re.compile(r'\[(.+)\]\((.+)\)')

    def issue_replace(match):
        url = "%s/issues/%s" % (BASE_URL, match.group(1))
        return "`%s <%s>`__" % (match.group(0), url)

    fo.write("Change log\n"
             "==========\n\n")

    for line in open('./CHANGE_LOG'):
        line = line.rstrip()
        match = ver_pat.match(line)
        if match:
            line = match.expand(r'**\2** (\1):')
        elif line.startswith('-----'):
            line = ''
        elif line.startswith('  '):
            line = line[2:]
        line = line.replace('`', '``')
        line = issue_pat.sub(issue_replace, line)
        line = link_pat.sub(
                    lambda m: "`%s <%s>`__" % (m.group(1), m.group(2)), line)
        fo.write(line + '\n')


def main():
    if len(sys.argv) > 1:
        sys.exit("no arguments expected")

    update_readme('./README.rst')
    with open('./doc/reference.rst', 'w') as fo:
        write_reference(fo)
    with open('./doc/changelog.rst', 'w') as fo:
        write_changelog(fo)

    doctest.testfile('./README.rst')
    doctest.testfile('./doc/buffer.rst')
    doctest.testfile('./doc/represent.rst')
    doctest.testfile('./doc/variable_length.rst')


if __name__ == '__main__':
    main()