sphinx / sphinx / builder.py

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
# -*- coding: utf-8 -*-
"""
    sphinx.builder
    ~~~~~~~~~~~~~~

    Builder classes for different output formats.

    :copyright: 2007 by Georg Brandl.
    :license: Python license.
"""
from __future__ import with_statement

import os
import sys
import time
import types
import codecs
import shutil
import cPickle as pickle
import cStringIO as StringIO
from os import path

from docutils.io import StringOutput, DocTreeInput
from docutils.core import publish_parts
from docutils.utils import new_document
from docutils.readers import doctree
from docutils.frontend import OptionParser

from .util import (get_matching_files, attrdict, status_iterator,
                   ensuredir, get_category, relative_uri)
from .writer import HTMLWriter
from .util.console import bold, purple, green
from .htmlhelp import build_hhx
from .patchlevel import get_version_info, get_sys_version_info
from .environment import BuildEnvironment
from .highlighting import pygments, get_stylesheet

# side effect: registers roles and directives
from . import roles
from . import directives

ENV_PICKLE_FILENAME = 'environment.pickle'
LAST_BUILD_FILENAME = 'last_build'

# Helper objects

class relpath_to(object):
    def __init__(self, builder, filename):
        self.baseuri = builder.get_target_uri(filename)
        self.builder = builder
    def __call__(self, otheruri, resource=False):
        if not resource:
            otheruri = self.builder.get_target_uri(otheruri)
        return relative_uri(self.baseuri, otheruri)


class collect_env_warnings(object):
    def __init__(self, builder):
        self.builder = builder
    def __enter__(self):
        self.stream = StringIO.StringIO()
        self.builder.env.set_warning_stream(self.stream)
    def __exit__(self, *args):
        self.builder.env.set_warning_stream(self.builder.warning_stream)
        warnings = self.stream.getvalue()
        if warnings:
            print >>self.builder.warning_stream, warnings


class Builder(object):
    """
    Builds target formats from the reST sources.
    """

    option_spec = {
        'freshenv': 'Don\'t use a pickled environment',
    }

    def __init__(self, srcdirname, outdirname, options, env=None,
                 status_stream=None, warning_stream=None,
                 confoverrides=None):
        self.srcdir = srcdirname
        self.outdir = outdirname
        if not path.isdir(path.join(outdirname, '.doctrees')):
            os.mkdir(path.join(outdirname, '.doctrees'))

        self.options = attrdict(options)
        self.validate_options()

        # probably set in load_env()
        self.env = env

        self.config = {}
        execfile(path.join(srcdirname, 'conf.py'), self.config)
        # remove potentially pickling-problematic values
        del self.config['__builtins__']
        for key, val in self.config.items():
            if isinstance(val, types.ModuleType):
                del self.config[key]
        if confoverrides:
            self.config.update(confoverrides)
        # replace version info if 'auto'
        if self.config['version'] == 'auto' or self.config['revision'] == 'auto':
            try:
                version, release = get_version_info(srcdirname)
            except (IOError, OSError):
                print >>warning_stream, 'WARNING: Can\'t get version info from ' \
                      'Include/patchlevel.h, using version of this interpreter.'
                version, release = get_sys_version_info()
            if self.config['version'] == 'auto':
                self.config['version'] = version
            if self.config['release'] == 'auto':
                self.config['release'] = release

        self.status_stream = status_stream or sys.stdout
        self.warning_stream = warning_stream or sys.stderr

        self.init()

    # helper methods

    def validate_options(self):
        for option in self.options:
            if option not in self.option_spec:
                raise ValueError('Got unexpected option %s' % option)
        for option in self.option_spec:
            if option not in self.options:
                self.options[option] = False

    def msg(self, message='', nonl=False, nobold=False):
        if not nobold: message = bold(message)
        if nonl:
            print >>self.status_stream, message,
        else:
            print >>self.status_stream, message
        self.status_stream.flush()

    def init(self):
        """Load necessary templates and perform initialization."""
        raise NotImplementedError

    def get_target_uri(self, source_filename):
        """Return the target URI for a source filename."""
        raise NotImplementedError

    def get_relative_uri(self, from_, to):
        """Return a relative URI between two source filenames."""
        return relative_uri(self.get_target_uri(from_),
                            self.get_target_uri(to))

    def get_outdated_files(self):
        """Return a list of output files that are outdated."""
        raise NotImplementedError

    # build methods

    def load_env(self):
        """Set up the build environment. Return True if a pickled file could be
           successfully loaded, False if a new environment had to be created."""
        if self.env:
            return
        if not self.options.freshenv:
            try:
                self.msg('trying to load pickled env...', nonl=True)
                self.env = BuildEnvironment.frompickle(
                    path.join(self.outdir, ENV_PICKLE_FILENAME))
                self.msg('done', nobold=True)
            except Exception, err:
                self.msg('failed: %s' % err, nobold=True)
                self.env = BuildEnvironment(self.srcdir,
                                            path.join(self.outdir, '.doctrees'))
        else:
            self.env = BuildEnvironment(self.srcdir,
                                        path.join(self.outdir, '.doctrees'))

    def build_all(self):
        """Build all source files."""
        self.load_env()
        self.build(None, summary='all source files')

    def build_specific(self, source_filenames):
        """Only rebuild as much as needed for changes in the source_filenames."""
        # bring the filenames to the canonical format, that is,
        # relative to the source directory.
        dirlen = len(self.srcdir) + 1
        to_write = [path.abspath(filename)[dirlen:] for filename in source_filenames]
        self.load_env()
        self.build(to_write,
                   summary='%d source files given on command line' % len(to_write))

    def build_update(self):
        """Only rebuild files changed or added since last build."""
        self.load_env()
        to_build = list(self.get_outdated_files())
        if not to_build:
            self.msg('no files are out of date, exiting.')
            return
        self.build(to_build,
                   summary='%d source files that are out of date' % len(to_build))

    def build(self, filenames, summary=None):
        if summary:
            self.msg('building [%s]:' % self.name, nonl=1)
            self.msg(summary, nobold=1)

        # while reading, collect all warnings from docutils
        with collect_env_warnings(self):
            self.msg('reading, updating environment:', nonl=1)
            iterator = self.env.update(self.config)
            self.msg(iterator.next(), nobold=1)
            for filename in iterator:
                self.msg(purple(filename), nonl=1, nobold=1)
            self.msg()

        # save the environment
        self.msg('pickling the env...', nonl=True)
        self.env.topickle(path.join(self.outdir, ENV_PICKLE_FILENAME))
        self.msg('done', nobold=True)

        # global actions
        self.msg('checking consistency...')
        self.env.check_consistency()
        self.msg('creating index...')
        self.env.create_index(self)

        self.prepare_writing()

        if filenames:
            # add all TOC files that may have changed
            filenames_set = set(filenames)
            for filename in filenames:
                for tocfilename in self.env.files_to_rebuild.get(filename, []):
                    filenames_set.add(tocfilename)
            filenames_set.add('contents.rst')
        else:
            # build all
            filenames_set = set(self.env.all_files)

        # write target files
        with collect_env_warnings(self):
            self.msg('writing output...')
            for filename in status_iterator(sorted(filenames_set), green,
                                            stream=self.status_stream):
                doctree = self.env.get_and_resolve_doctree(filename, self)
                self.write_file(filename, doctree)

        # finish (write style files etc.)
        self.msg('finishing...')
        self.finish()
        self.msg('done!')

    def prepare_writing(self):
        raise NotImplementedError

    def write_file(self, filename, doctree):
        raise NotImplementedError

    def finish(self):
        raise NotImplementedError


class StandaloneHTMLBuilder(Builder):
    """
    Builds standalone HTML docs.
    """
    name = 'html'

    option_spec = Builder.option_spec
    option_spec.update({
        'nostyle': 'Don\'t copy style and script files',
        'nosearchindex': 'Don\'t create a JSON search index for offline search',
    })

    copysource = True

    def init(self):
        """Load templates."""
        # lazily import this, maybe other builders won't need it
        from ._jinja import Environment, FileSystemLoader

        # load templates
        self.templates = {}
        templates_path = path.join(path.dirname(__file__), 'templates')
        jinja_env = Environment(loader=FileSystemLoader(templates_path),
                                # disable traceback, more likely that something in the
                                # application is broken than in the templates
                                friendly_traceback=False)
        for fname in os.listdir(templates_path):
            if fname.endswith('.html'):
                self.templates[fname[:-5]] = jinja_env.get_template(fname)

    def render_partial(self, node):
        """Utility: Render a lone doctree node."""
        doc = new_document('foo')
        doc.append(node)
        return publish_parts(
            doc,
            source_class=DocTreeInput,
            reader=doctree.Reader(),
            writer=HTMLWriter(self.config),
            settings_overrides={'output_encoding': 'unicode'}
        )

    def prepare_writing(self):
        if not self.options.nosearchindex:
            from .search import IndexBuilder
            self.indexer = IndexBuilder()
        else:
            self.indexer = None
        self.docwriter = HTMLWriter(self.config)
        self.docsettings = OptionParser(
            defaults=self.env.settings,
            components=(self.docwriter,)).get_default_values()

        # format the "last updated on" string, only once is enough since it
        # typically doesn't include the time of day
        lufmt = self.config.get('last_updated_format')
        if lufmt:
            self.last_updated = time.strftime(lufmt)
        else:
            self.last_updated = None

        self.globalcontext = dict(
            last_updated = self.last_updated,
            builder = self.name,
            release = self.config['release'],
            version = self.config['version'],
            parents = [],
            len = len,
            titles = {},
        )

    def write_file(self, filename, doctree):
        destination = StringOutput(encoding='utf-8')
        doctree.settings = self.docsettings

        output = self.docwriter.write(doctree, destination)
        self.docwriter.assemble_parts()

        prev = next = None
        parents = []
        related = self.env.toctree_relations.get(filename)
        if related:
            prev = {'link': self.get_relative_uri(filename, related[1]),
                    'title': self.render_partial(self.env.titles[related[1]])['title']}
            next = {'link': self.get_relative_uri(filename, related[2]),
                    'title': self.render_partial(self.env.titles[related[2]])['title']}
        while related:
            parents.append(
                {'link': self.get_relative_uri(filename, related[0]),
                 'title': self.render_partial(self.env.titles[related[0]])['title']})
            related = self.env.toctree_relations.get(related[0])
        if parents:
            parents.pop() # remove link to "contents.rst"; we have a generic
                          # "back to index" link already
        parents.reverse()

        title = self.env.titles.get(filename)
        if title:
            title = self.render_partial(title)['title']
        else:
            title = ''
        self.globalcontext['titles'][filename] = title
        sourcename = filename[:-4] + '.txt'
        context = dict(
            title = title,
            sourcename = sourcename,
            pathto = relpath_to(self, self.get_target_uri(filename)),
            body = self.docwriter.parts['fragment'],
            toc = self.render_partial(self.env.get_toc_for(filename))['fragment'],
            # only display a TOC if there's more than one item to show
            display_toc = (self.env.toc_num_entries[filename] > 1),
            parents = parents,
            prev = prev,
            next = next,
        )

        self.index_file(filename, doctree, title)
        self.handle_file(filename, context)

    def finish(self):
        self.msg('writing additional files...')

        # the global general index

        # the total count of lines for each index letter, used to distribute
        # the entries into two columns
        indexcounts = []
        for key, entries in self.env.index:
            indexcounts.append(sum(1 + len(subitems) for _, (_, subitems) in entries))

        genindexcontext = dict(
            genindexentries = self.env.index,
            genindexcounts = indexcounts,
            current_page_name = 'genindex',
            pathto = relpath_to(self, self.get_target_uri('genindex.rst')),
        )
        self.handle_file('genindex.rst', genindexcontext, 'genindex')

        # the global module index

        # the sorted list of all modules, for the global module index
        modules = sorted(((mn, (self.get_relative_uri('modindex.rst', fn) +
                                '#module-' + mn, sy, pl))
                          for (mn, (fn, sy, pl)) in self.env.modules.iteritems()),
                         key=lambda x: x[0].lower())
        # collect all platforms
        platforms = set()
        # sort out collapsable modules
        modindexentries = []
        pmn = ''
        cg = 0 # collapse group
        fl = '' # first letter
        for mn, (fn, sy, pl) in modules:
            pl = pl.split(', ') if pl else []
            platforms.update(pl)
            if fl != mn[0].lower() and mn[0] != '_':
                modindexentries.append(['', False, 0, False, mn[0].upper(), '', []])
            tn = mn.partition('.')[0]
            if tn != mn:
                # submodule
                if pmn == tn:
                    # first submodule - make parent collapsable
                    modindexentries[-1][1] = True
                elif not pmn.startswith(tn):
                    # submodule without parent in list, add dummy entry
                    cg += 1
                    modindexentries.append([tn, True, cg, False, '', '', []])
            else:
                cg += 1
            modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl])
            pmn = mn
            fl = mn[0].lower()
        platforms = sorted(platforms)

        modindexcontext = dict(
            modindexentries = modindexentries,
            platforms = platforms,
            current_page_name = 'modindex',
            pathto = relpath_to(self, self.get_target_uri('modindex.rst')),
        )
        self.handle_file('modindex.rst', modindexcontext, 'modindex')

        # the download page
        downloadcontext = dict(
            pathto = relpath_to(self, self.get_target_uri('download.rst')),
            current_page_name = 'download',
            download_base_url = self.config['download_base_url'],
        )
        self.handle_file('download.rst', downloadcontext, 'download')

        # the index page
        indexcontext = dict(
            pathto = relpath_to(self, self.get_target_uri('index.rst')),
            current_page_name = 'index',
        )
        self.handle_file('index.rst', indexcontext, 'index')

        # the search page
        searchcontext = dict(
            pathto = relpath_to(self, self.get_target_uri('search.rst')),
            current_page_name = 'search',
        )
        self.handle_file('search.rst', searchcontext, 'search')

        if not self.options.nostyle:
            self.msg('copying style files...')
            # copy style files
            styledirname = path.join(path.dirname(__file__), 'style')
            ensuredir(path.join(self.outdir, 'style'))
            for filename in os.listdir(styledirname):
                if not filename.startswith('.'):
                    shutil.copyfile(path.join(styledirname, filename),
                                    path.join(self.outdir, 'style', filename))
            # add pygments style file
            f = open(path.join(self.outdir, 'style', 'pygments.css'), 'w')
            if pygments:
                f.write(get_stylesheet())
            f.close()

        # dump the search index
        self.handle_finish()

    # --------- these are overwritten by the Web builder

    def get_target_uri(self, source_filename):
        return source_filename[:-4] + '.html'

    def get_outdated_files(self):
        for filename in get_matching_files(
            self.srcdir, '*.rst', exclude=set(self.config.get('unused_files', ()))):
            try:
                targetmtime = path.getmtime(path.join(self.outdir,
                                                      filename[:-4] + '.html'))
            except:
                targetmtime = 0
            if path.getmtime(path.join(self.srcdir, filename)) > targetmtime:
                yield filename

    def index_file(self, filename, doctree, title):
        # only index pages with title
        if self.indexer is not None and title:
            category = get_category(filename)
            if category is not None:
                self.indexer.feed(self.get_target_uri(filename)[:-5], # strip '.html'
                                  category, title, doctree)

    def handle_file(self, filename, context, templatename='page'):
        ctx = self.globalcontext.copy()
        ctx.update(context)
        output = self.templates[templatename].render(ctx)
        outfilename = path.join(self.outdir, filename[:-4] + '.html')
        ensuredir(path.dirname(outfilename)) # normally different from self.outdir
        try:
            with codecs.open(outfilename, 'w', 'utf-8') as fp:
                fp.write(output)
        except (IOError, OSError), err:
            print >>self.warning_stream, "Error writing file %s: %s" % (outfilename, err)
        if self.copysource and context.get('sourcename'):
            # copy the source file for the "show source" link
            shutil.copyfile(path.join(self.srcdir, filename),
                            path.join(self.outdir, context['sourcename']))

    def handle_finish(self):
        if self.indexer is not None:
            self.msg('dumping search index...')
            f = open(path.join(self.outdir, 'searchindex.json'), 'w')
            self.indexer.dump(f, 'json')
            f.close()


class WebHTMLBuilder(StandaloneHTMLBuilder):
    """
    Builds HTML docs usable with the web-based doc server.
    """
    name = 'web'

    # doesn't use the standalone specific options
    option_spec = Builder.option_spec.copy()
    option_spec.update({
        'nostyle': 'Don\'t copy style and script files',
        'nosearchindex': 'Don\'t create a search index for the online search',
    })

    def init(self):
        # Nothing to do here.
        pass

    def get_outdated_files(self):
        for filename in get_matching_files(
            self.srcdir, '*.rst', exclude=set(self.config.get('unused_files', ()))):
            try:
                targetmtime = path.getmtime(path.join(self.outdir,
                                                      filename[:-4] + '.fpickle'))
            except:
                targetmtime = 0
            if path.getmtime(path.join(self.srcdir, filename)) > targetmtime:
                yield filename

    def get_target_uri(self, source_filename):
        if source_filename == 'index.rst':
            return ''
        if source_filename.endswith('/index.rst'):
            return source_filename[:-9] # up to /
        return source_filename[:-4] + '/'

    def index_file(self, filename, doctree, title):
        # only index pages with title and category
        if self.indexer is not None and title:
            category = get_category(filename)
            if category is not None:
                self.indexer.feed(filename, category, title, doctree)

    def handle_file(self, filename, context, templatename='page'):
        outfilename = path.join(self.outdir, filename[:-4] + '.fpickle')
        ensuredir(path.dirname(outfilename))
        context.pop('pathto', None) # can't be pickled
        with file(outfilename, 'wb') as fp:
            pickle.dump(context, fp, 2)

        # if there is a source file, copy the source file for the "show source" link
        if context.get('sourcename'):
            source_name = path.join(self.outdir, 'sources', context['sourcename'])
            ensuredir(path.dirname(source_name))
            shutil.copyfile(path.join(self.srcdir, filename), source_name)

    def handle_finish(self):
        # dump the global context
        outfilename = path.join(self.outdir, 'globalcontext.pickle')
        with file(outfilename, 'wb') as fp:
            pickle.dump(self.globalcontext, fp, 2)

        if self.indexer is not None:
            self.msg('dumping search index...')
            f = open(path.join(self.outdir, 'searchindex.pickle'), 'w')
            self.indexer.dump(f, 'pickle')
            f.close()
        # touch 'last build' file, used by the web application to determine
        # when to reload its environment and clear the cache
        open(path.join(self.outdir, LAST_BUILD_FILENAME), 'w').close()
        # copy configuration file if not present
        if not path.isfile(path.join(self.outdir, 'webconf.py')):
            shutil.copyfile(path.join(path.dirname(__file__), 'web', 'webconf.py'),
                            path.join(self.outdir, 'webconf.py'))


class HTMLHelpBuilder(StandaloneHTMLBuilder):
    """
    Builder that also outputs Windows HTML help project, contents and index files.
    Adapted from the original Doc/tools/prechm.py.
    """
    name = 'htmlhelp'

    option_spec = Builder.option_spec.copy()
    option_spec.update({
        'outname': 'Output file base name (default "pydoc")'
    })

    # don't copy the reST source
    copysource = False

    def handle_finish(self):
        build_hhx(self, self.outdir, self.options.get('outname') or 'pydoc')


builders = {
    'html': StandaloneHTMLBuilder,
    'web': WebHTMLBuilder,
    'htmlhelp': HTMLHelpBuilder,
}
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.