| 1 | #!/usr/bin/env python |
|---|
| 2 | |
|---|
| 3 | |
|---|
| 4 | """Script for rebuilding our documentation.""" |
|---|
| 5 | |
|---|
| 6 | |
|---|
| 7 | import sys |
|---|
| 8 | import os.path |
|---|
| 9 | |
|---|
| 10 | from docutils import nodes, core |
|---|
| 11 | from docutils.parsers import rst |
|---|
| 12 | |
|---|
| 13 | |
|---|
| 14 | # (limited) support for trac wiki links. |
|---|
| 15 | # This is copied and hacked up from rst.py in the trac source. |
|---|
| 16 | |
|---|
| 17 | def trac_get_reference(rawtext, link, text): |
|---|
| 18 | if not link.startswith('rst:'): |
|---|
| 19 | return None |
|---|
| 20 | target = link.split(':', 1)[1] |
|---|
| 21 | reference = nodes.reference(rawtext, text or target) |
|---|
| 22 | reference['refuri'] = target |
|---|
| 23 | return reference |
|---|
| 24 | |
|---|
| 25 | def trac(name, arguments, options, content, lineno, |
|---|
| 26 | content_offset, block_text, state, state_machine): |
|---|
| 27 | """Inserts a `reference` node into the document |
|---|
| 28 | for a given `TracLink`_, based on the content |
|---|
| 29 | of the arguments. |
|---|
| 30 | |
|---|
| 31 | Usage:: |
|---|
| 32 | |
|---|
| 33 | .. trac:: target [text] |
|---|
| 34 | |
|---|
| 35 | ``target`` may be any `TracLink`_, provided it doesn't |
|---|
| 36 | embed a space character (e.g. wiki:"..." notation won't work). |
|---|
| 37 | |
|---|
| 38 | ``[text]`` is optional. If not given, ``target`` is |
|---|
| 39 | used as the reference text. |
|---|
| 40 | |
|---|
| 41 | .. _TracLink: http://trac.edgewall.org/wiki/TracLinks |
|---|
| 42 | """ |
|---|
| 43 | link = arguments[0] |
|---|
| 44 | if len(arguments) == 2: |
|---|
| 45 | text = arguments[1] |
|---|
| 46 | else: |
|---|
| 47 | text = None |
|---|
| 48 | reference = trac_get_reference(block_text, link, text) |
|---|
| 49 | if reference: |
|---|
| 50 | p = nodes.paragraph() |
|---|
| 51 | p += reference |
|---|
| 52 | return p |
|---|
| 53 | # didn't find a match (invalid TracLink), |
|---|
| 54 | # report a warning |
|---|
| 55 | warning = state_machine.reporter.warning( |
|---|
| 56 | '%s is not a valid TracLink' % (arguments[0]), |
|---|
| 57 | nodes.literal_block(block_text, block_text), |
|---|
| 58 | line=lineno) |
|---|
| 59 | return [warning] |
|---|
| 60 | |
|---|
| 61 | def trac_role(name, rawtext, text, lineno, inliner, options={}, |
|---|
| 62 | content=[]): |
|---|
| 63 | args = text.split(" ",1) |
|---|
| 64 | link = args[0] |
|---|
| 65 | if len(args)==2: |
|---|
| 66 | text = args[1] |
|---|
| 67 | else: |
|---|
| 68 | text = None |
|---|
| 69 | reference = trac_get_reference(rawtext, link, text) |
|---|
| 70 | if reference: |
|---|
| 71 | return [reference], [] |
|---|
| 72 | warning = nodes.warning(None, nodes.literal_block(text, |
|---|
| 73 | 'WARNING: %s is not a valid TracLink' % rawtext)) |
|---|
| 74 | return warning, [] |
|---|
| 75 | |
|---|
| 76 | # 1 required arg, 1 optional arg, spaces allowed in last arg |
|---|
| 77 | trac.arguments = (1,1,1) |
|---|
| 78 | trac.options = None |
|---|
| 79 | trac.content = None |
|---|
| 80 | rst.directives.register_directive('trac', trac) |
|---|
| 81 | rst.roles.register_local_role('trac', trac_role) |
|---|
| 82 | |
|---|
| 83 | |
|---|
| 84 | """Spit out a restructuredtext file linking to every .rst in cwd.""" |
|---|
| 85 | |
|---|
| 86 | |
|---|
| 87 | def process(directory, force): |
|---|
| 88 | """Generate the table of contents and html files.""" |
|---|
| 89 | print 'processing %s' % (directory,) |
|---|
| 90 | # Dirs first so we pick up their contents when generating ours. |
|---|
| 91 | for child in os.listdir(directory): |
|---|
| 92 | target = os.path.join(directory, child) |
|---|
| 93 | if os.path.isdir(target): |
|---|
| 94 | process(target, force) |
|---|
| 95 | # Write the table of contents .rst file while processing files. |
|---|
| 96 | tocpath = os.path.join(directory, 'toc.rst') |
|---|
| 97 | out = open(tocpath, 'w') |
|---|
| 98 | try: |
|---|
| 99 | out.write('===================\n') |
|---|
| 100 | out.write(' Table of contents\n') |
|---|
| 101 | out.write('===================\n') |
|---|
| 102 | out.write('\n') |
|---|
| 103 | for entry in os.listdir(directory): |
|---|
| 104 | original = os.path.join(directory, entry) |
|---|
| 105 | if entry == 'toc.rst': |
|---|
| 106 | continue |
|---|
| 107 | if entry.lower().endswith('.rst'): |
|---|
| 108 | base = entry[:-4] |
|---|
| 109 | target = os.path.join(directory, base) + '.html' |
|---|
| 110 | out.write('- `%s <%s.html>`_\n' % (base, base)) |
|---|
| 111 | # Check if we need to reprocess. |
|---|
| 112 | if force or not os.path.exists(target) or ( |
|---|
| 113 | os.path.getmtime(target) < os.path.getmtime(original)): |
|---|
| 114 | print 'writing %s' % (target,) |
|---|
| 115 | core.publish_file(source_path=original, |
|---|
| 116 | destination_path=target, |
|---|
| 117 | writer_name='html') |
|---|
| 118 | else: |
|---|
| 119 | print 'up to date: %s' % (target,) |
|---|
| 120 | elif (os.path.isdir(original) and |
|---|
| 121 | os.path.exists(os.path.join(original, 'toc.rst'))): |
|---|
| 122 | out.write('- `%s <%s.html>`_\n' % |
|---|
| 123 | (entry, "%s/toc.rst" % entry)) |
|---|
| 124 | finally: |
|---|
| 125 | out.close() |
|---|
| 126 | # And convert the toc. |
|---|
| 127 | # (Guess we could keep the toc rst only in memory but who knows, someone |
|---|
| 128 | # might want to read it!) |
|---|
| 129 | core.publish_file(source_path=tocpath, |
|---|
| 130 | destination_path=os.path.join(directory, 'toc.html'), |
|---|
| 131 | writer_name='html') |
|---|
| 132 | |
|---|
| 133 | |
|---|
| 134 | if __name__ == '__main__': |
|---|
| 135 | print 'checking documentation, use --force to force rebuild' |
|---|
| 136 | print |
|---|
| 137 | force = '--force' in sys.argv |
|---|
| 138 | for directory in ['dev-notes', 'doc']: |
|---|
| 139 | process(os.path.join(os.path.dirname(__file__), directory), force) |
|---|
