tools/buildhtml.py

   1 #!/usr/bin/env python
   2
   3 # $Id$
   4 # Author: David Goodger <goodger@python.org>
   5 # Copyright: This module has been placed in the public domain.
   6
   7 """
   8 Generates .html from all the .txt files in a directory.
   9
  10 Ordinary .txt files are understood to be standalone reStructuredText.
  11 Files named ``pep-*.txt`` are interpreted as reStructuredText PEPs.
  12 """
  13 # Once PySource is here, build .html from .py as well.
  14
  15 __docformat__ = 'reStructuredText'
  16
  17
  18 try:
  19     import locale
  20     locale.setlocale(locale.LC_ALL, '')
  21 except:
  22     pass
  23
  24 import sys
  25 import os
  26 import os.path
  27 import copy
  28 from fnmatch import fnmatch
  29 import docutils
  30 from docutils import ApplicationError
  31 from docutils import core, frontend, utils
  32 from docutils.error_reporting import ErrorOutput, ErrorString
  33 from docutils.parsers import rst
  34 from docutils.readers import standalone, pep
  35 from docutils.writers import html4css1, pep_html
  36
  37
  38 usage = '%prog [options] [<directory> ...]'
  39 description = ('Generates .html from all the reStructuredText .txt files '
  40                '(including PEPs) in each <directory> '
  41                '(default is the current directory).')
  42
  43
  44 class SettingsSpec(docutils.SettingsSpec):
  45
  46     """
  47     Runtime settings & command-line options for the front end.
  48     """
  49
  50     # Can't be included in OptionParser below because we don't want to
  51     # override the base class.
  52     settings_spec = (
  53         'Build-HTML Options',
  54         None,
  55         (('Recursively scan subdirectories for files to process.  This is '
  56           'the default.',
  57           ['--recurse'],
  58           {'action': 'store_true', 'default': 1,
  59            'validator': frontend.validate_boolean}),
  60          ('Do not scan subdirectories for files to process.',
  61           ['--local'], {'dest': 'recurse', 'action': 'store_false'}),
  62          ('BROKEN Do not process files in <directory>.  This option may be used '
  63           'more than once to specify multiple directories.',
  64           ['--prune'],
  65           {'metavar': '<directory>', 'action': 'append',
  66            'validator': frontend.validate_colon_separated_string_list}),
  67          ('BROKEN Recursively ignore files or directories matching any of the given '
  68           'wildcard (shell globbing) patterns (separated by colons).  '
  69           'Default: ".svn:CVS"',
  70           ['--ignore'],
  71           {'metavar': '<patterns>', 'action': 'append',
  72            'default': ['.svn', 'CVS'],
  73            'validator': frontend.validate_colon_separated_string_list}),
  74          ('Work silently (no progress messages).  Independent of "--quiet".',
  75           ['--silent'],
  76           {'action': 'store_true', 'validator': frontend.validate_boolean}),
  77          ('Do not process files, show files that would be processed.',
  78           ['--dry-run'],
  79           {'action': 'store_true', 'validator': frontend.validate_boolean}),))
  80
  81     relative_path_settings = ('prune',)
  82     config_section = 'buildhtml application'
  83     config_section_dependencies = ('applications',)
  84
  85
  86 class OptionParser(frontend.OptionParser):
  87
  88     """
  89     Command-line option processing for the ``buildhtml.py`` front end.
  90     """
  91
  92     def check_values(self, values, args):
  93         frontend.OptionParser.check_values(self, values, args)
  94         values._source = None
  95         return values
  96
  97     def check_args(self, args):
  98         source = destination = None
  99         if args:
 100             self.values._directories = args
 101         else:
 102             self.values._directories = [os.getcwd()]
 103         return source, destination
 104
 105
 106 class Struct:
 107
 108     """Stores data attributes for dotted-attribute access."""
 109
 110     def __init__(self, **keywordargs):
 111         self.__dict__.update(keywordargs)
 112
 113
 114 class Builder:
 115
 116     def __init__(self):
 117         self.publishers = {
 118             '': Struct(components=(pep.Reader, rst.Parser, pep_html.Writer,
 119                                    SettingsSpec)),
 120             '.txt': Struct(components=(rst.Parser, standalone.Reader,
 121                                        html4css1.Writer, SettingsSpec),
 122                            reader_name='standalone',
 123                            writer_name='html'),
 124             'PEPs': Struct(components=(rst.Parser, pep.Reader,
 125                                        pep_html.Writer, SettingsSpec),
 126                            reader_name='pep',
 127                            writer_name='pep_html')}
 128         """Publisher-specific settings.  Key '' is for the front-end script
 129         itself.  ``self.publishers[''].components`` must contain a superset of
 130         all components used by individual publishers."""
 131
 132         self.setup_publishers()
 133
 134     def setup_publishers(self):
 135         """
 136         Manage configurations for individual publishers.
 137
 138         Each publisher (combination of parser, reader, and writer) may have
 139         its own configuration defaults, which must be kept separate from those
 140         of the other publishers.  Setting defaults are combined with the
 141         config file settings and command-line options by
 142         `self.get_settings()`.
 143         """
 144         for name, publisher in self.publishers.items():
 145             option_parser = OptionParser(
 146                 components=publisher.components, read_config_files=1,
 147                 usage=usage, description=description)
 148             publisher.option_parser = option_parser
 149             publisher.setting_defaults = option_parser.get_default_values()
 150             frontend.make_paths_absolute(publisher.setting_defaults.__dict__,
 151                                          option_parser.relative_path_settings)
 152             publisher.config_settings = (
 153                 option_parser.get_standard_config_settings())
 154         self.settings_spec = self.publishers[''].option_parser.parse_args(
 155             values=frontend.Values())   # no defaults; just the cmdline opts
 156         self.initial_settings = self.get_settings('')
 157
 158     def get_settings(self, publisher_name, directory=None):
 159         """
 160         Return a settings object, from multiple sources.
 161
 162         Copy the setting defaults, overlay the startup config file settings,
 163         then the local config file settings, then the command-line options.
 164         Assumes the current directory has been set.
 165         """
 166         publisher = self.publishers[publisher_name]
 167         settings = frontend.Values(publisher.setting_defaults.__dict__)
 168         settings.update(publisher.config_settings, publisher.option_parser)
 169         if directory:
 170             local_config = publisher.option_parser.get_config_file_settings(
 171                 os.path.join(directory, 'docutils.conf'))
 172             frontend.make_paths_absolute(
 173                 local_config, publisher.option_parser.relative_path_settings,
 174                 directory)
 175             settings.update(local_config, publisher.option_parser)
 176         settings.update(self.settings_spec.__dict__, publisher.option_parser)
 177         return settings
 178
 179     def run(self, directory=None, recurse=1):
 180         recurse = recurse and self.initial_settings.recurse
 181         if directory:
 182             self.directories = [directory]
 183         elif self.settings_spec._directories:
 184             self.directories = self.settings_spec._directories
 185         else:
 186             self.directories = [os.getcwd()]
 187         for directory in self.directories:
 188             for root, dirs, files in os.walk(directory):
 189                 # os.walk by default this recurses down the tree,
 190                 # influence by modifying dirs.
 191                 if not recurse:
 192                     del dirs[:]
 193                 self.visit(root, files)
 194
 195     def visit(self, directory, names):
 196         # BUG prune and ignore do not work
 197         settings = self.get_settings('', directory)
 198         errout = ErrorOutput(encoding=settings.error_encoding)
 199         if settings.prune and (os.path.abspath(directory) in settings.prune):
 200             print >>errout, ('/// ...Skipping directory (pruned): %s' %
 201                               directory)
 202             sys.stderr.flush()
 203             names[:] = []
 204             return
 205         if not self.initial_settings.silent:
 206             print >>errout, '/// Processing directory: %s' % directory
 207             sys.stderr.flush()
 208         # settings.ignore grows many duplicate entries as we recurse
 209         # if we add patterns in config files or on the command line.
 210         for pattern in utils.uniq(settings.ignore):
 211             for i in range(len(names) - 1, -1, -1):
 212                 if fnmatch(names[i], pattern):
 213                     # Modify in place!
 214                     del names[i]
 215         prune = 0
 216         for name in names:
 217             if name.endswith('.txt'):
 218                 prune = self.process_txt(directory, name)
 219                 if prune:
 220                     break
 221
 222     def process_txt(self, directory, name):
 223         if name.startswith('pep-'):
 224             publisher = 'PEPs'
 225         else:
 226             publisher = '.txt'
 227         settings = self.get_settings(publisher, directory)
 228         errout = ErrorOutput(encoding=settings.error_encoding)
 229         pub_struct = self.publishers[publisher]
 230         if settings.prune and (directory in settings.prune):
 231             return 1
 232         settings._source = os.path.normpath(os.path.join(directory, name))
 233         settings._destination = settings._source[:-4]+'.html'
 234         if not self.initial_settings.silent:
 235             print >>errout, '    ::: Processing: %s' % name
 236             sys.stderr.flush()
 237         try:
 238             if not settings.dry_run:
 239                 core.publish_file(source_path=settings._source,
 240                               destination_path=settings._destination,
 241                               reader_name=pub_struct.reader_name,
 242                               parser_name='restructuredtext',
 243                               writer_name=pub_struct.writer_name,
 244                               settings=settings)
 245         except ApplicationError, error:
 246             print >>errout, '        %s' % ErrorString(error)
 247
 248
 249 if __name__ == "__main__":
 250     Builder().run()