##// END OF EJS Templates
added gh-pages command for GitHub hosted sphinx docs
MinRK -
Show More
@@ -0,0 +1,381 b''
1 #! /usr/bin/env python
2 """
3 sphinxtogithub extension Copyright Michael Jones
4
5 BSD License
6
7 Original at: https://github.com/michaeljones/sphinx-to-github
8 """
9 from optparse import OptionParser
10 import os
11 import sys
12 import shutil
13
14
15 class DirHelper(object):
16
17 def __init__(self, is_dir, list_dir, walk, rmtree):
18
19 self.is_dir = is_dir
20 self.list_dir = list_dir
21 self.walk = walk
22 self.rmtree = rmtree
23
24 class FileSystemHelper(object):
25
26 def __init__(self, open_, path_join, move, exists):
27
28 self.open_ = open_
29 self.path_join = path_join
30 self.move = move
31 self.exists = exists
32
33 class Replacer(object):
34 "Encapsulates a simple text replace"
35
36 def __init__(self, from_, to):
37
38 self.from_ = from_
39 self.to = to
40
41 def process(self, text):
42
43 return text.replace( self.from_, self.to )
44
45 class FileHandler(object):
46 "Applies a series of replacements the contents of a file inplace"
47
48 def __init__(self, name, replacers, opener):
49
50 self.name = name
51 self.replacers = replacers
52 self.opener = opener
53
54 def process(self):
55
56 text = self.opener(self.name).read()
57
58 for replacer in self.replacers:
59 text = replacer.process( text )
60
61 self.opener(self.name, "w").write(text)
62
63 class Remover(object):
64
65 def __init__(self, exists, remove):
66 self.exists = exists
67 self.remove = remove
68
69 def __call__(self, name):
70
71 if self.exists(name):
72 self.remove(name)
73
74 class ForceRename(object):
75
76 def __init__(self, renamer, remove):
77
78 self.renamer = renamer
79 self.remove = remove
80
81 def __call__(self, from_, to):
82
83 self.remove(to)
84 self.renamer(from_, to)
85
86 class VerboseRename(object):
87
88 def __init__(self, renamer, stream):
89
90 self.renamer = renamer
91 self.stream = stream
92
93 def __call__(self, from_, to):
94
95 self.stream.write(
96 "Renaming directory '%s' -> '%s'\n"
97 % (os.path.basename(from_), os.path.basename(to))
98 )
99
100 self.renamer(from_, to)
101
102
103 class DirectoryHandler(object):
104 "Encapsulates renaming a directory by removing its first character"
105
106 def __init__(self, name, root, renamer):
107
108 self.name = name
109 self.new_name = name[1:]
110 self.root = root + os.sep
111 self.renamer = renamer
112
113 def path(self):
114
115 return os.path.join(self.root, self.name)
116
117 def relative_path(self, directory, filename):
118
119 path = directory.replace(self.root, "", 1)
120 return os.path.join(path, filename)
121
122 def new_relative_path(self, directory, filename):
123
124 path = self.relative_path(directory, filename)
125 return path.replace(self.name, self.new_name, 1)
126
127 def process(self):
128
129 from_ = os.path.join(self.root, self.name)
130 to = os.path.join(self.root, self.new_name)
131 self.renamer(from_, to)
132
133
134 class HandlerFactory(object):
135
136 def create_file_handler(self, name, replacers, opener):
137
138 return FileHandler(name, replacers, opener)
139
140 def create_dir_handler(self, name, root, renamer):
141
142 return DirectoryHandler(name, root, renamer)
143
144
145 class OperationsFactory(object):
146
147 def create_force_rename(self, renamer, remover):
148
149 return ForceRename(renamer, remover)
150
151 def create_verbose_rename(self, renamer, stream):
152
153 return VerboseRename(renamer, stream)
154
155 def create_replacer(self, from_, to):
156
157 return Replacer(from_, to)
158
159 def create_remover(self, exists, remove):
160
161 return Remover(exists, remove)
162
163
164 class Layout(object):
165 """
166 Applies a set of operations which result in the layout
167 of a directory changing
168 """
169
170 def __init__(self, directory_handlers, file_handlers):
171
172 self.directory_handlers = directory_handlers
173 self.file_handlers = file_handlers
174
175 def process(self):
176
177 for handler in self.file_handlers:
178 handler.process()
179
180 for handler in self.directory_handlers:
181 handler.process()
182
183
184 class NullLayout(object):
185 """
186 Layout class that does nothing when asked to process
187 """
188 def process(self):
189 pass
190
191 class LayoutFactory(object):
192 "Creates a layout object"
193
194 def __init__(self, operations_factory, handler_factory, file_helper, dir_helper, verbose, stream, force):
195
196 self.operations_factory = operations_factory
197 self.handler_factory = handler_factory
198
199 self.file_helper = file_helper
200 self.dir_helper = dir_helper
201
202 self.verbose = verbose
203 self.output_stream = stream
204 self.force = force
205
206 def create_layout(self, path):
207
208 contents = self.dir_helper.list_dir(path)
209
210 renamer = self.file_helper.move
211
212 if self.force:
213 remove = self.operations_factory.create_remover(self.file_helper.exists, self.dir_helper.rmtree)
214 renamer = self.operations_factory.create_force_rename(renamer, remove)
215
216 if self.verbose:
217 renamer = self.operations_factory.create_verbose_rename(renamer, self.output_stream)
218
219 # Build list of directories to process
220 directories = [d for d in contents if self.is_underscore_dir(path, d)]
221 underscore_directories = [
222 self.handler_factory.create_dir_handler(d, path, renamer)
223 for d in directories
224 ]
225
226 if not underscore_directories:
227 if self.verbose:
228 self.output_stream.write(
229 "No top level directories starting with an underscore "
230 "were found in '%s'\n" % path
231 )
232 return NullLayout()
233
234 # Build list of files that are in those directories
235 replacers = []
236 for handler in underscore_directories:
237 for directory, dirs, files in self.dir_helper.walk(handler.path()):
238 for f in files:
239 replacers.append(
240 self.operations_factory.create_replacer(
241 handler.relative_path(directory, f),
242 handler.new_relative_path(directory, f)
243 )
244 )
245
246 # Build list of handlers to process all files
247 filelist = []
248 for root, dirs, files in self.dir_helper.walk(path):
249 for f in files:
250 if f.endswith(".html"):
251 filelist.append(
252 self.handler_factory.create_file_handler(
253 self.file_helper.path_join(root, f),
254 replacers,
255 self.file_helper.open_)
256 )
257 if f.endswith(".js"):
258 filelist.append(
259 self.handler_factory.create_file_handler(
260 self.file_helper.path_join(root, f),
261 [self.operations_factory.create_replacer("'_sources/'", "'sources/'")],
262 self.file_helper.open_
263 )
264 )
265
266 return Layout(underscore_directories, filelist)
267
268 def is_underscore_dir(self, path, directory):
269
270 return (self.dir_helper.is_dir(self.file_helper.path_join(path, directory))
271 and directory.startswith("_"))
272
273
274
275 def sphinx_extension(app, exception):
276 "Wrapped up as a Sphinx Extension"
277
278 if not app.builder.name in ("html", "dirhtml"):
279 return
280
281 if not app.config.sphinx_to_github:
282 if app.config.sphinx_to_github_verbose:
283 print "Sphinx-to-github: Disabled, doing nothing."
284 return
285
286 if exception:
287 if app.config.sphinx_to_github_verbose:
288 print "Sphinx-to-github: Exception raised in main build, doing nothing."
289 return
290
291 dir_helper = DirHelper(
292 os.path.isdir,
293 os.listdir,
294 os.walk,
295 shutil.rmtree
296 )
297
298 file_helper = FileSystemHelper(
299 open,
300 os.path.join,
301 shutil.move,
302 os.path.exists
303 )
304
305 operations_factory = OperationsFactory()
306 handler_factory = HandlerFactory()
307
308 layout_factory = LayoutFactory(
309 operations_factory,
310 handler_factory,
311 file_helper,
312 dir_helper,
313 app.config.sphinx_to_github_verbose,
314 sys.stdout,
315 force=True
316 )
317
318 layout = layout_factory.create_layout(app.outdir)
319 layout.process()
320
321
322 def setup(app):
323 "Setup function for Sphinx Extension"
324
325 app.add_config_value("sphinx_to_github", True, '')
326 app.add_config_value("sphinx_to_github_verbose", True, '')
327
328 app.connect("build-finished", sphinx_extension)
329
330
331 def main(args):
332
333 usage = "usage: %prog [options] <html directory>"
334 parser = OptionParser(usage=usage)
335 parser.add_option("-v","--verbose", action="store_true",
336 dest="verbose", default=False, help="Provides verbose output")
337 opts, args = parser.parse_args(args)
338
339 try:
340 path = args[0]
341 except IndexError:
342 sys.stderr.write(
343 "Error - Expecting path to html directory:"
344 "sphinx-to-github <path>\n"
345 )
346 return
347
348 dir_helper = DirHelper(
349 os.path.isdir,
350 os.listdir,
351 os.walk,
352 shutil.rmtree
353 )
354
355 file_helper = FileSystemHelper(
356 open,
357 os.path.join,
358 shutil.move,
359 os.path.exists
360 )
361
362 operations_factory = OperationsFactory()
363 handler_factory = HandlerFactory()
364
365 layout_factory = LayoutFactory(
366 operations_factory,
367 handler_factory,
368 file_helper,
369 dir_helper,
370 opts.verbose,
371 sys.stdout,
372 force=False
373 )
374
375 layout = layout_factory.create_layout(path)
376 layout.process()
377
378
379
380 if __name__ == "__main__":
381 main(sys.argv[1:])
@@ -0,0 +1,31 b''
1 #!/usr/bin/env sh
2 # pick repo for gh-pages branch
3 repo=origin
4
5 if [ ! -d gh-pages ]; then
6 echo "setting up gh-pages subdir"
7 mkdir gh-pages || exit -1
8 cp -r ../.git gh-pages/ || exit -1
9 cd gh-pages || exit -1
10 init=0
11 git checkout $repo/gh-pages || init=1
12 if [ "$init" != "0" ]; then
13 echo "initializing gh-pages repo"
14 git symbolic-ref HEAD refs/heads/gh-pages || exit -1
15 rm .git/index || exit -1
16 git clean -fdx || exit -1
17 touch index.html
18 git add .
19 git commit -a -m 'init gh-pages' || exit -1
20 git push origin HEAD:gh-pages
21 fi
22 cd ..
23 fi
24 echo "updating local gh-pages with html build"
25 rsync -va build/html/ gh-pages/ --delete --exclude .git || exit -1
26 cd gh-pages
27 git add .
28 git commit -a || exit -1
29 echo "pushing to remote gh-pages"
30 # pwd
31 git push $repo HEAD:gh-pages
@@ -1,10 +1,11 b''
1 1 build
2 2 ./dist
3 3 docs/dist
4 4 docs/build/*
5 5 docs/source/api/generated
6 docs/gh-pages
6 7 *.py[co]
7 8 build
8 9 *.egg-info
9 10 *~
10 11 *.bak
@@ -1,104 +1,107 b''
1 1 # Makefile for Sphinx documentation
2 2 #
3 3
4 4 # You can set these variables from the command line.
5 5 SPHINXOPTS =
6 6 SPHINXBUILD = sphinx-build
7 7 PAPER =
8 8 SRCDIR = source
9 9
10 10 # Internal variables.
11 11 PAPEROPT_a4 = -D latex_paper_size=a4
12 12 PAPEROPT_letter = -D latex_paper_size=letter
13 13 ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
14 14
15 15 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
16 16
17 17 default: html
18 18
19 19 help:
20 20 @echo "Please use \`make <target>' where <target> is one of"
21 21 @echo " html to make standalone HTML files"
22 22 @echo " pickle to make pickle files (usable by e.g. sphinx-web)"
23 23 @echo " htmlhelp to make HTML files and a HTML help project"
24 24 @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
25 25 @echo " changes to make an overview over all changed/added/deprecated items"
26 26 @echo " linkcheck to check all external links for integrity"
27 27 @echo
28 28 @echo "Compound utility targets:"
29 29 @echo "pdf latex and then runs the PDF generation"
30 30 @echo "all html and pdf"
31 31 @echo "dist all, and then puts the results in dist/"
32 32 @echo "gitwash-update update git workflow from source repo"
33 33
34 34 clean:
35 35 -rm -rf build/* dist/* $(SRCDIR)/api/generated
36 36
37 37 pdf: latex
38 38 cd build/latex && make all-pdf
39 39
40 40 all: html pdf
41 41
42 42 dist: all
43 43 mkdir -p dist
44 44 rm -rf dist/*
45 45 ln build/latex/ipython.pdf dist/
46 46 cp -al build/html dist/
47 47 @echo "Build finished. Final docs are in dist/"
48 48
49 49 html: api
50 50 mkdir -p build/html build/doctrees
51 51 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
52 52 @echo
53 53 @echo "Build finished. The HTML pages are in build/html."
54 54
55 55 api: source/api/generated/gen.txt
56 56
57 57 source/api/generated/gen.txt:
58 58 python autogen_api.py
59 59 @echo "Build API docs finished."
60 60
61 61 pickle:
62 62 mkdir -p build/pickle build/doctrees
63 63 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
64 64 @echo
65 65 @echo "Build finished; now you can process the pickle files or run"
66 66 @echo " sphinx-web build/pickle"
67 67 @echo "to start the sphinx-web server."
68 68
69 69 web: pickle
70 70
71 71 htmlhelp:
72 72 mkdir -p build/htmlhelp build/doctrees
73 73 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
74 74 @echo
75 75 @echo "Build finished; now you can run HTML Help Workshop with the" \
76 76 ".hhp project file in build/htmlhelp."
77 77
78 78 latex: api
79 79 mkdir -p build/latex build/doctrees
80 80 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
81 81 @echo
82 82 @echo "Build finished; the LaTeX files are in build/latex."
83 83 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
84 84 "run these through (pdf)latex."
85 85
86 86 changes:
87 87 mkdir -p build/changes build/doctrees
88 88 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
89 89 @echo
90 90 @echo "The overview file is in build/changes."
91 91
92 92 linkcheck:
93 93 mkdir -p build/linkcheck build/doctrees
94 94 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
95 95 @echo
96 96 @echo "Link check complete; look for any errors in the above output " \
97 97 "or in build/linkcheck/output.txt."
98 98
99 99 gitwash-update:
100 100 python ../tools/gitwash_dumper.py source/development ipython
101 101 cd source/development/gitwash && rename 's/.rst/.txt/' *.rst
102 102
103 103 nightly: dist
104 104 rsync -avH --delete dist/ ipython:www/doc/nightly
105
106 gh-pages: html
107 sh update_ghpages.sh
@@ -1,195 +1,196 b''
1 1 # -*- coding: utf-8 -*-
2 2 #
3 3 # IPython documentation build configuration file.
4 4
5 5 # NOTE: This file has been edited manually from the auto-generated one from
6 6 # sphinx. Do NOT delete and re-generate. If any changes from sphinx are
7 7 # needed, generate a scratch one and merge by hand any new fields needed.
8 8
9 9 #
10 10 # This file is execfile()d with the current directory set to its containing dir.
11 11 #
12 12 # The contents of this file are pickled, so don't put values in the namespace
13 13 # that aren't pickleable (module imports are okay, they're removed automatically).
14 14 #
15 15 # All configuration values have a default value; values that are commented out
16 16 # serve to show the default value.
17 17
18 18 import sys, os
19 19
20 20 # If your extensions are in another directory, add it here. If the directory
21 21 # is relative to the documentation root, use os.path.abspath to make it
22 22 # absolute, like shown here.
23 sys.path.append(os.path.abspath('../sphinxext'))
23 sys.path.insert(0, os.path.abspath('../sphinxext'))
24 24
25 25 # Import support for ipython console session syntax highlighting (lives
26 26 # in the sphinxext directory defined above)
27 27 import ipython_console_highlighting
28 28
29 29 # We load the ipython release info into a dict by explicit execution
30 30 iprelease = {}
31 31 execfile('../../IPython/core/release.py',iprelease)
32 32
33 33 # General configuration
34 34 # ---------------------
35 35
36 36 # Add any Sphinx extension module names here, as strings. They can be extensions
37 37 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
38 38 extensions = [
39 39 # 'matplotlib.sphinxext.mathmpl',
40 40 'matplotlib.sphinxext.only_directives',
41 41 # 'matplotlib.sphinxext.plot_directive',
42 42 'sphinx.ext.autodoc',
43 43 'sphinx.ext.doctest',
44 44 'inheritance_diagram',
45 45 'ipython_console_highlighting',
46 46 'numpydoc', # to preprocess docstrings
47 'sphinxtogithub',
47 48 ]
48 49
49 50 # Add any paths that contain templates here, relative to this directory.
50 51 templates_path = ['_templates']
51 52
52 53 # The suffix of source filenames.
53 54 source_suffix = '.txt'
54 55
55 56 # The master toctree document.
56 57 master_doc = 'index'
57 58
58 59 # General substitutions.
59 60 project = 'IPython'
60 61 copyright = '2008, The IPython Development Team'
61 62
62 63 # The default replacements for |version| and |release|, also used in various
63 64 # other places throughout the built documents.
64 65 #
65 66 # The full version, including alpha/beta/rc tags.
66 67 release = iprelease['version']
67 68 # The short X.Y version.
68 69 version = '.'.join(release.split('.',2)[:2])
69 70
70 71
71 72 # There are two options for replacing |today|: either, you set today to some
72 73 # non-false value, then it is used:
73 74 #today = ''
74 75 # Else, today_fmt is used as the format for a strftime call.
75 76 today_fmt = '%B %d, %Y'
76 77
77 78 # List of documents that shouldn't be included in the build.
78 79 #unused_docs = []
79 80
80 81 # List of directories, relative to source directories, that shouldn't be searched
81 82 # for source files.
82 83 exclude_dirs = ['attic']
83 84
84 85 # If true, '()' will be appended to :func: etc. cross-reference text.
85 86 #add_function_parentheses = True
86 87
87 88 # If true, the current module name will be prepended to all description
88 89 # unit titles (such as .. function::).
89 90 #add_module_names = True
90 91
91 92 # If true, sectionauthor and moduleauthor directives will be shown in the
92 93 # output. They are ignored by default.
93 94 #show_authors = False
94 95
95 96 # The name of the Pygments (syntax highlighting) style to use.
96 97 pygments_style = 'sphinx'
97 98
98 99
99 100 # Options for HTML output
100 101 # -----------------------
101 102
102 103 # The style sheet to use for HTML and HTML Help pages. A file of that name
103 104 # must exist either in Sphinx' static/ path, or in one of the custom paths
104 105 # given in html_static_path.
105 106 html_style = 'default.css'
106 107
107 108 # The name for this set of Sphinx documents. If None, it defaults to
108 109 # "<project> v<release> documentation".
109 110 #html_title = None
110 111
111 112 # The name of an image file (within the static path) to place at the top of
112 113 # the sidebar.
113 114 #html_logo = None
114 115
115 116 # Add any paths that contain custom static files (such as style sheets) here,
116 117 # relative to this directory. They are copied after the builtin static files,
117 118 # so a file named "default.css" will overwrite the builtin "default.css".
118 119 html_static_path = ['_static']
119 120
120 121 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
121 122 # using the given strftime format.
122 123 html_last_updated_fmt = '%b %d, %Y'
123 124
124 125 # If true, SmartyPants will be used to convert quotes and dashes to
125 126 # typographically correct entities.
126 127 #html_use_smartypants = True
127 128
128 129 # Custom sidebar templates, maps document names to template names.
129 130 #html_sidebars = {}
130 131
131 132 # Additional templates that should be rendered to pages, maps page names to
132 133 # template names.
133 134 #html_additional_pages = {}
134 135
135 136 # If false, no module index is generated.
136 137 #html_use_modindex = True
137 138
138 139 # If true, the reST sources are included in the HTML build as _sources/<name>.
139 140 #html_copy_source = True
140 141
141 142 # If true, an OpenSearch description file will be output, and all pages will
142 143 # contain a <link> tag referring to it. The value of this option must be the
143 144 # base URL from which the finished HTML is served.
144 145 #html_use_opensearch = ''
145 146
146 147 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
147 148 #html_file_suffix = ''
148 149
149 150 # Output file base name for HTML help builder.
150 151 htmlhelp_basename = 'ipythondoc'
151 152
152 153
153 154 # Options for LaTeX output
154 155 # ------------------------
155 156
156 157 # The paper size ('letter' or 'a4').
157 158 latex_paper_size = 'letter'
158 159
159 160 # The font size ('10pt', '11pt' or '12pt').
160 161 latex_font_size = '11pt'
161 162
162 163 # Grouping the document tree into LaTeX files. List of tuples
163 164 # (source start file, target name, title, author, document class [howto/manual]).
164 165
165 166 latex_documents = [
166 167 ('index', 'ipython.tex', 'IPython Documentation',
167 168 ur"""The IPython Development Team""", 'manual', True),
168 169 ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
169 170 'Using IPython on Windows HPC Server 2008',
170 171 ur"Brian E. Granger", 'manual', True)
171 172 ]
172 173
173 174 # The name of an image file (relative to this directory) to place at the top of
174 175 # the title page.
175 176 #latex_logo = None
176 177
177 178 # For "manual" documents, if this is true, then toplevel headings are parts,
178 179 # not chapters.
179 180 #latex_use_parts = False
180 181
181 182 # Additional stuff for the LaTeX preamble.
182 183 #latex_preamble = ''
183 184
184 185 # Documents to append as an appendix to all manuals.
185 186 #latex_appendices = []
186 187
187 188 # If false, no module index is generated.
188 189 latex_use_modindex = True
189 190
190 191
191 192 # Cleanup
192 193 # -------
193 194 # delete release info to avoid pickling errors from sphinx
194 195
195 196 del iprelease
General Comments 0
You need to be logged in to leave comments. Login now