extras/sphinxtogithub/sphinxtogithub.py

   1 #! /usr/bin/env python
   2
   3 from optparse import OptionParser
   4 import warnings
   5 import os
   6 import sys
   7 import shutil
   8
   9
  10 class DirHelper(object):
  11
  12     def __init__(self, is_dir, list_dir, walk, rmtree):
  13
  14         self.is_dir = is_dir
  15         self.list_dir = list_dir
  16         self.walk = walk
  17         self.rmtree = rmtree
  18
  19 class FileSystemHelper(object):
  20
  21     def __init__(self, open_, path_join, move, exists):
  22
  23         self.open_ = open_
  24         self.path_join = path_join
  25         self.move = move
  26         self.exists = exists
  27
  28 class Replacer(object):
  29     "Encapsulates a simple text replace"
  30
  31     def __init__(self, from_, to):
  32
  33         self.from_ = from_
  34         self.to = to
  35
  36     def process(self, text):
  37
  38         return text.replace( self.from_, self.to )
  39
  40 class FileHandler(object):
  41     "Applies a series of replacements the contents of a file inplace"
  42
  43     def __init__(self, name, replacers, opener):
  44
  45         self.name = name
  46         self.replacers = replacers
  47         self.opener = opener
  48
  49     def process(self):
  50
  51         text = self.opener(self.name).read()
  52
  53         for replacer in self.replacers:
  54             text = replacer.process( text )
  55
  56         self.opener(self.name, "w").write(text)
  57
  58 class Remover(object):
  59
  60     def __init__(self, exists, remove):
  61         self.exists = exists
  62         self.remove = remove
  63
  64     def __call__(self, name):
  65
  66         if self.exists(name):
  67             self.remove(name)
  68
  69 class ForceRename(object):
  70
  71     def __init__(self, renamer, remove):
  72
  73         self.renamer = renamer
  74         self.remove = remove
  75
  76     def __call__(self, from_, to):
  77
  78         self.remove(to)
  79         self.renamer(from_, to)
  80
  81 class VerboseRename(object):
  82
  83     def __init__(self, renamer, stream):
  84
  85         self.renamer = renamer
  86         self.stream = stream
  87
  88     def __call__(self, from_, to):
  89
  90         self.stream.write(
  91                 "Renaming directory '%s' -> '%s'\n"
  92                     % (os.path.basename(from_), os.path.basename(to))
  93                 )
  94
  95         self.renamer(from_, to)
  96
  97
  98 class DirectoryHandler(object):
  99     "Encapsulates renaming a directory by removing its first character"
 100
 101     def __init__(self, name, root, renamer):
 102
 103         self.name = name
 104         self.new_name = name[1:]
 105         self.root = root + os.sep
 106         self.renamer = renamer
 107
 108     def path(self):
 109
 110         return os.path.join(self.root, self.name)
 111
 112     def relative_path(self, directory, filename):
 113
 114         path = directory.replace(self.root, "", 1)
 115         return os.path.join(path, filename)
 116
 117     def new_relative_path(self, directory, filename):
 118
 119         path = self.relative_path(directory, filename)
 120         return path.replace(self.name, self.new_name, 1)
 121
 122     def process(self):
 123
 124         from_ = os.path.join(self.root, self.name)
 125         to = os.path.join(self.root, self.new_name)
 126         self.renamer(from_, to)
 127
 128
 129 class HandlerFactory(object):
 130
 131     def create_file_handler(self, name, replacers, opener):
 132
 133         return FileHandler(name, replacers, opener)
 134
 135     def create_dir_handler(self, name, root, renamer):
 136
 137         return DirectoryHandler(name, root, renamer)
 138
 139
 140 class OperationsFactory(object):
 141
 142     def create_force_rename(self, renamer, remover):
 143
 144         return ForceRename(renamer, remover)
 145
 146     def create_verbose_rename(self, renamer, stream):
 147
 148         return VerboseRename(renamer, stream)
 149
 150     def create_replacer(self, from_, to):
 151
 152         return Replacer(from_, to)
 153
 154     def create_remover(self, exists, remove):
 155
 156         return Remover(exists, remove)
 157
 158
 159 class Layout(object):
 160     """
 161     Applies a set of operations which result in the layout
 162     of a directory changing
 163     """
 164
 165     def __init__(self, directory_handlers, file_handlers):
 166
 167         self.directory_handlers = directory_handlers
 168         self.file_handlers = file_handlers
 169
 170     def process(self):
 171
 172         for handler in self.file_handlers:
 173             handler.process()
 174
 175         for handler in self.directory_handlers:
 176             handler.process()
 177
 178
 179 class NullLayout(object):
 180     """
 181     Layout class that does nothing when asked to process
 182     """
 183     def process(self):
 184         pass
 185
 186 class LayoutFactory(object):
 187     "Creates a layout object"
 188
 189     def __init__(self, operations_factory, handler_factory, file_helper, dir_helper, verbose, stream, force):
 190
 191         self.operations_factory = operations_factory
 192         self.handler_factory = handler_factory
 193
 194         self.file_helper = file_helper
 195         self.dir_helper = dir_helper
 196
 197         self.verbose = verbose
 198         self.output_stream = stream
 199         self.force = force
 200
 201     def create_layout(self, path):
 202
 203         contents = self.dir_helper.list_dir(path)
 204
 205         renamer = self.file_helper.move
 206
 207         if self.force:
 208             remove = self.operations_factory.create_remover(self.file_helper.exists, self.dir_helper.rmtree)
 209             renamer = self.operations_factory.create_force_rename(renamer, remove)
 210
 211         if self.verbose:
 212             renamer = self.operations_factory.create_verbose_rename(renamer, self.output_stream)
 213
 214         # Build list of directories to process
 215         directories = [d for d in contents if self.is_underscore_dir(path, d)]
 216         underscore_directories = [
 217                 self.handler_factory.create_dir_handler(d, path, renamer)
 218                     for d in directories
 219                 ]
 220
 221         if not underscore_directories:
 222             if self.verbose:
 223                 self.output_stream.write(
 224                         "No top level directories starting with an underscore "
 225                         "were found in '%s'\n" % path
 226                         )
 227             return NullLayout()
 228
 229         # Build list of files that are in those directories
 230         replacers = []
 231         for handler in underscore_directories:
 232             for directory, dirs, files in self.dir_helper.walk(handler.path()):
 233                 for f in files:
 234                     replacers.append(
 235                             self.operations_factory.create_replacer(
 236                                 handler.relative_path(directory, f),
 237                                 handler.new_relative_path(directory, f)
 238                                 )
 239                             )
 240
 241         # Build list of handlers to process all files
 242         filelist = []
 243         for root, dirs, files in self.dir_helper.walk(path):
 244             for f in files:
 245                 if f.endswith(".html"):
 246                     filelist.append(
 247                             self.handler_factory.create_file_handler(
 248                                 self.file_helper.path_join(root, f),
 249                                 replacers,
 250                                 self.file_helper.open_)
 251                             )
 252                 if f.endswith(".js"):
 253                     filelist.append(
 254                             self.handler_factory.create_file_handler(
 255                                 self.file_helper.path_join(root, f),
 256                                 [self.operations_factory.create_replacer("'_sources/'", "'sources/'")],
 257                                 self.file_helper.open_
 258                                 )
 259                             )
 260
 261         return Layout(underscore_directories, filelist)
 262
 263     def is_underscore_dir(self, path, directory):
 264
 265         return (self.dir_helper.is_dir(self.file_helper.path_join(path, directory))
 266             and directory.startswith("_"))
 267
 268
 269
 270 def sphinx_extension(app, exception):
 271     "Wrapped up as a Sphinx Extension"
 272
 273     if not app.builder.name in ("html", "dirhtml"):
 274         return
 275
 276     if not app.config.sphinx_to_github:
 277         if app.config.sphinx_to_github_verbose:
 278             print "Sphinx-to-github: Disabled, doing nothing."
 279         return
 280
 281     if exception:
 282         if app.config.sphinx_to_github_verbose:
 283             print "Sphinx-to-github: Exception raised in main build, doing nothing."
 284         return
 285
 286     dir_helper = DirHelper(
 287             os.path.isdir,
 288             os.listdir,
 289             os.walk,
 290             shutil.rmtree
 291             )
 292
 293     file_helper = FileSystemHelper(
 294             open,
 295             os.path.join,
 296             shutil.move,
 297             os.path.exists
 298             )
 299
 300     operations_factory = OperationsFactory()
 301     handler_factory = HandlerFactory()
 302
 303     layout_factory = LayoutFactory(
 304             operations_factory,
 305             handler_factory,
 306             file_helper,
 307             dir_helper,
 308             app.config.sphinx_to_github_verbose,
 309             sys.stdout,
 310             force=True
 311             )
 312
 313     layout = layout_factory.create_layout(app.outdir)
 314     layout.process()
 315
 316
 317 def setup(app):
 318     "Setup function for Sphinx Extension"
 319
 320     if (not hasattr(app, 'add_config_value') or
 321         not hasattr(app, 'connect')):
 322         warnings.warn('Could not call add_config_value() in sphinxtogithub')
 323         return
 324     app.add_config_value("sphinx_to_github", True, '')
 325     app.add_config_value("sphinx_to_github_verbose", True, '')
 326     app.connect("build-finished", sphinx_extension)
 327
 328
 329 def main(args):
 330
 331     usage = "usage: %prog [options] <html directory>"
 332     parser = OptionParser(usage=usage)
 333     parser.add_option("-v","--verbose", action="store_true",
 334             dest="verbose", default=False, help="Provides verbose output")
 335     opts, args = parser.parse_args(args)
 336
 337     try:
 338         path = args[0]
 339     except IndexError:
 340         sys.stderr.write(
 341                 "Error - Expecting path to html directory:"
 342                 "sphinx-to-github <path>\n"
 343                 )
 344         return
 345
 346     dir_helper = DirHelper(
 347             os.path.isdir,
 348             os.listdir,
 349             os.walk,
 350             shutil.rmtree
 351             )
 352
 353     file_helper = FileSystemHelper(
 354             open,
 355             os.path.join,
 356             shutil.move,
 357             os.path.exists
 358             )
 359
 360     operations_factory = OperationsFactory()
 361     handler_factory = HandlerFactory()
 362
 363     layout_factory = LayoutFactory(
 364             operations_factory,
 365             handler_factory,
 366             file_helper,
 367             dir_helper,
 368             opts.verbose,
 369             sys.stdout,
 370             force=False
 371             )
 372
 373     layout = layout_factory.create_layout(path)
 374     layout.process()
 375
 376
 377
 378 if __name__ == "__main__":
 379     main(sys.argv[1:])
 380
 381
 382