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
|
# -*- coding: utf-8 -*-
"""
sphinx.builders.websupport
~~~~~~~~~~~~~~~~~~~~~~~~~~
Builder for the web support package.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import cPickle as pickle
from os import path
from cgi import escape
import os
import posixpath
import shutil
from docutils.io import StringOutput
from docutils.utils import Reporter
from sphinx.util.osutil import os_path, relative_uri, ensuredir, copyfile
from sphinx.util.jsonimpl import dumps as dump_json
from sphinx.util.websupport import is_commentable
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.writers.websupport import WebSupportTranslator
from sphinx.environment import WarningStream
from sphinx.versioning import add_uids, merge_doctrees
class WebSupportBuilder(StandaloneHTMLBuilder):
"""
Builds documents for the web support package.
"""
name = 'websupport'
out_suffix = '.fpickle'
def init(self):
StandaloneHTMLBuilder.init(self)
for root, dirs, files in os.walk(self.doctreedir):
for fn in files:
fp = path.join(root, fn)
if fp.endswith('.doctree'):
copyfile(fp, fp + '.old')
def init_translator_class(self):
self.translator_class = WebSupportTranslator
def get_old_doctree(self, docname):
fp = self.env.doc2path(docname, self.doctreedir, '.doctree.old')
try:
f = open(fp, 'rb')
try:
doctree = pickle.load(f)
finally:
f.close()
except IOError:
return None
doctree.settings.env = self.env
doctree.reporter = Reporter(self.env.doc2path(docname), 2, 5,
stream=WarningStream(self.env._warnfunc))
return doctree
def resave_doctree(self, docname, doctree):
# make it picklable, save the reporter, it's needed later.
reporter = doctree.reporter
doctree.reporter = None
doctree.settings.warning_stream = None
doctree.settings.env = None
doctree.settings.record_dependencies = None
fp = self.env.doc2path(docname, self.doctreedir, '.doctree')
f = open(fp, 'wb')
try:
pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
finally:
f.close()
doctree.reporter = reporter
def write_doc(self, docname, doctree):
destination = StringOutput(encoding='utf-8')
doctree.settings = self.docsettings
old_doctree = self.get_old_doctree(docname)
if old_doctree:
list(merge_doctrees(old_doctree, doctree, is_commentable))
else:
list(add_uids(doctree, is_commentable))
self.resave_doctree(docname, doctree)
self.cur_docname = docname
self.secnumbers = self.env.toc_secnumbers.get(docname, {})
self.imgpath = '/' + posixpath.join(self.app.staticdir, '_images')
self.post_process_images(doctree)
self.dlpath = '/' + posixpath.join(self.app.staticdir, '_downloads')
self.docwriter.write(doctree, destination)
self.docwriter.assemble_parts()
body = self.docwriter.parts['fragment']
metatags = self.docwriter.clean_meta
ctx = self.get_doc_context(docname, body, metatags)
self.index_page(docname, doctree, ctx.get('title', ''))
self.handle_page(docname, ctx, event_arg=doctree)
def get_target_uri(self, docname, typ=None):
return docname
def load_indexer(self, docnames):
self.indexer = self.app.search
self.indexer.init_indexing(changed=docnames)
def handle_page(self, pagename, addctx, templatename='page.html',
outfilename=None, event_arg=None):
# This is mostly copied from StandaloneHTMLBuilder. However, instead
# of rendering the template and saving the html, create a context
# dict and pickle it.
ctx = self.globalcontext.copy()
ctx['pagename'] = pagename
def pathto(otheruri, resource=False,
baseuri=self.get_target_uri(pagename)):
if not resource:
otheruri = self.get_target_uri(otheruri)
return relative_uri(baseuri, otheruri) or '#'
else:
return '/' + posixpath.join(self.app.staticdir, otheruri)
ctx['pathto'] = pathto
ctx['hasdoc'] = lambda name: name in self.env.all_docs
ctx['encoding'] = encoding = self.config.html_output_encoding
ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw)
self.add_sidebars(pagename, ctx)
ctx.update(addctx)
self.app.emit('html-page-context', pagename, templatename,
ctx, event_arg)
# Create a dict that will be pickled and used by webapps.
css = '<link rel="stylesheet" href="%s" type=text/css />' % \
pathto('_static/pygments.css', 1)
doc_ctx = {'body': ctx.get('body', ''),
'title': ctx.get('title', ''),
'css': css,
'js': self._make_js(ctx)}
# Partially render the html template to proved a more useful ctx.
template = self.templates.environment.get_template(templatename)
template_module = template.make_module(ctx)
if hasattr(template_module, 'sidebar'):
doc_ctx['sidebar'] = template_module.sidebar()
if hasattr(template_module, 'relbar'):
doc_ctx['relbar'] = template_module.relbar()
if not outfilename:
outfilename = path.join(self.outdir, 'pickles',
os_path(pagename) + self.out_suffix)
ensuredir(path.dirname(outfilename))
f = open(outfilename, 'wb')
try:
pickle.dump(doc_ctx, f, pickle.HIGHEST_PROTOCOL)
finally:
f.close()
# if there is a source file, copy the source file for the
# "show source" link
if ctx.get('sourcename'):
source_name = path.join(self.app.builddir, self.app.staticdir,
'_sources', os_path(ctx['sourcename']))
ensuredir(path.dirname(source_name))
copyfile(self.env.doc2path(pagename), source_name)
def handle_finish(self):
StandaloneHTMLBuilder.handle_finish(self)
directories = ['_images', '_static']
for directory in directories:
try:
shutil.move(path.join(self.outdir, directory),
path.join(self.app.builddir, self.app.staticdir,
directory))
except IOError:
# in case any of these directories don't exist
pass
for root, dirs, files in os.walk(self.doctreedir):
for fn in files:
fp = path.join(root, fn)
if fp.endswith('.doctree.old'):
os.remove(fp)
def dump_search_index(self):
self.indexer.finish_indexing()
def _make_js(self, ctx):
def make_script(file):
path = ctx['pathto'](file, 1)
return '<script type="text/javascript" src="%s"></script>' % path
opts = {
'URL_ROOT': ctx.get('url_root', ''),
'VERSION': ctx['release'],
'COLLAPSE_INDEX': False,
'FILE_SUFFIX': '',
'HAS_SOURCE': ctx['has_source']
}
scripts = [make_script(file) for file in ctx['script_files']]
scripts.append(make_script('_static/websupport.js'))
return '\n'.join([
'<script type="text/javascript">'
'var DOCUMENTATION_OPTIONS = %s;' % dump_json(opts),
'</script>'
] + scripts)
|
