2 This is a generic SCons script for running Sphinx (http://sphinx.pocoo.org).
4 Type 'scons -h' for help. This prints the available build targets on your
5 system, and the configuration options you can set.
7 If you set the 'cache' option, the option settings are cached into a file
8 called '.sconsrc-sphinx' in the current directory. When running
9 subsequently, this file is reread. A file with this name is also read from
10 your home directory, if it exists, so you can put global settings there.
12 The script looks into your 'conf.py' file for information about the
13 project. This is used in various places (e.g., to print the introductory
14 message, and create package files).
16 Here's some examples. To build HTML docs:
20 To create a package containing HTML and PDF docs, remembering the 'install'
23 scons install=html,pdf cache=True package
25 To clean up everything:
31 __author__ = "Glenn Hutchings"
32 __email__ = "zondo42@googlemail.com"
33 __url__ = "http://bitbucket.org/zondo/sphinx-scons"
41 ("html", "make standalone HTML files"),
42 ("dirhtml", "make HTML files named index.html in directories"),
43 ("pickle", "make pickle files"),
44 ("json", "make JSON files"),
45 ("htmlhelp", "make HTML files and a HTML help project"),
46 ("qthelp", "make HTML files and a qthelp project"),
47 ("devhelp", "make HTML files and a GNOME DevHelp project"),
48 ("epub", "make HTML files and an EPUB file for bookreaders"),
49 ("latex", "make LaTeX sources"),
50 ("text", "make text file for each RST file"),
51 ("pdf", "make PDF file from LaTeX sources"),
52 ("ps", "make PostScript file from LaTeX sources"),
53 ("dvi", "make DVI file from LaTeX sources"),
54 ("changes", "make an overview over all changed/added/deprecated items"),
55 ("linkcheck", "check all external links for integrity"),
56 ("doctest", "run all doctests embedded in the documentation if enabled"),
57 ("source", "run a command to generate the reStructuredText source"),
61 latex_builders = {"pdf": "PDF", "ps": "PostScript", "dvi": "DVI"}
63 # List of target names.
64 targetnames = [name for name, desc in targets]
66 # Configuration cache filename.
67 cachefile = ".sconsrc-sphinx"
70 homedir = os.path.expanduser('~')
71 usercache = os.path.join(homedir, cachefile)
73 # Configuration options.
74 config = Variables([usercache, cachefile], ARGUMENTS)
77 EnumVariable("default", "default build target", "html", targetnames),
78 PathVariable("config", "sphinx configuration file", "conf.py"),
79 PathVariable("srcdir", "source directory", ".",
80 PathVariable.PathIsDir),
81 PathVariable("builddir", "build directory", "build",
82 PathVariable.PathIsDirCreate),
83 PathVariable("doctrees", "place to put doctrees", None,
84 PathVariable.PathAccept),
85 EnumVariable("paper", "LaTeX paper size", None,
86 ["a4", "letter"], ignorecase = False),
87 ("tags", "comma-separated list of 'only' tags", None),
88 ("builder", "program to run to build things", "sphinx-build"),
89 ("opts", "extra builder options to use", None),
90 ListVariable("install", "targets to install", ["html"], targetnames),
91 PathVariable("instdir", "installation directory", "/usr/local/doc",
92 PathVariable.PathAccept),
93 EnumVariable("pkgtype", "package type to build with 'scons package'",
94 "zip", ["zip", "targz", "tarbz2"], ignorecase = False),
95 BoolVariable("cache", "whether to cache settings in %s" % cachefile, False),
96 BoolVariable("debug", "debugging flag", False),
97 ("genrst", "Command to regenerate reStructuredText source", None),
100 # Create a new environment, inheriting PATH to find builder program. Also
101 # force LaTeX instead of TeX, since the .tex file won't exist at the right
102 # time to check which one to use.
103 env = Environment(ENV = {"PATH" : os.environ["PATH"]},
104 TEX = "latex", PDFTEX = "pdflatex",
105 tools = ['default', 'packaging'],
107 if 'PYTHONPATH' in os.environ:
108 env['ENV']['PYTHONPATH'] = os.environ['PYTHONPATH']
110 # Get configuration values from environment.
111 sphinxconf = env["config"]
112 builder = env["builder"]
113 default = env["default"]
115 srcdir = env["srcdir"]
116 builddir = env["builddir"]
117 doctrees = env.get("doctrees", os.path.join(builddir, "doctrees"))
122 options = env.get("opts", None)
123 paper = env.get("paper", None)
124 tags = env.get("tags", None)
125 genrst = env.get("genrst", None)
127 instdir = env["instdir"]
128 install = env["install"]
129 pkgtype = env["pkgtype"]
131 # Dump internals if debugging.
136 # Get parameters from Sphinx config file.
138 execfile(sphinxconf, sphinxparams)
140 project = sphinxparams["project"]
141 release = sphinxparams["release"]
142 copyright = sphinxparams["copyright"]
145 texfilename = sphinxparams["latex_documents"][0][1]
149 name2tag = lambda name: name.replace(" ", "-").strip("()")
150 project_tag = name2tag(project)
151 release_tag = name2tag(release)
152 package_tag = project_tag.lower() + "-" + release_tag.lower()
154 # Build project description string.
155 description = "%(project)s, release %(release)s, " \
156 "copyright %(copyright)s" % locals()
158 Help(description + "\n\n")
159 help_format = " %-10s %s\n"
161 # Print banner if required.
162 if not any(map(GetOption, ("silent", "clean", "help"))):
164 print "This is", description
167 # Build sphinx command-line options.
171 opts.extend(["-t %s" % tag for tag in tags.split(",")])
174 opts.append("-D latex_paper_size=%s" % paper)
179 options = " ".join(opts)
181 # Build Sphinx command template.
183 %(builder)s -b %(name)s -d %(doctrees)s %(options)s %(srcdir)s %(targetdir)s
186 # Set up LaTeX input builder if required.
188 latexdir = Dir("latex", builddir)
189 texinput = File(texfilename, latexdir)
190 env.SideEffect(texinput, "latex")
191 env.NoClean(texinput)
194 Help("Build targets:\n\n")
197 source = env.Command('source', [], genrst, chdir = True)
198 env.AlwaysBuild(source)
199 env.Depends(srcdir, source)
201 source = env.Command(
203 '@echo "No reStructuredText generator (genrst) given."')
205 for name, desc in targets:
206 target = Dir(name, builddir)
207 targetdir = str(target)
211 elif name not in latex_builders:
212 # Standard Sphinx target.
213 targets = env.Command(name, sphinxconf,
214 sphinxcmd % locals(), chdir = True)
215 env.Depends(targets, source)
216 env.AlwaysBuild(name)
217 env.Alias(target, name)
219 # Target built from LaTeX sources.
221 buildfunc = getattr(env, latex_builders[name])
222 except AttributeError:
225 filename = project_tag + "." + name
226 outfile = File(filename, latexdir)
228 targets = buildfunc(outfile, texinput)
229 env.Depends(targets, source)
231 # Copy built file to separate directory.
232 target = File(filename, target)
233 env.Command(target, outfile, Move(target, outfile), chdir = True)
235 env.Alias(name, target)
239 env.Clean(name, [target])
240 env.Clean('all', target)
242 if name == default: desc += " (default)"
243 Help(help_format % (name, desc))
245 Clean('all', doctrees)
248 # Add installation targets and collect package sources.
249 Help("\nOther targets:\n\n")
251 Help(help_format % ("install", "install documentation"))
252 projectdir = os.path.join(instdir, project_tag)
256 source = Dir(name, builddir)
257 sources.append(source)
259 inst = env.Install(projectdir, source)
260 env.Alias('install', inst)
262 for node in env.Glob(os.path.join(str(source), '*')):
263 filename = str(node).replace(builddir + os.path.sep, "")
264 dirname = os.path.dirname(filename)
265 dest = os.path.join(projectdir, dirname)
266 inst = env.Install(dest, node)
267 env.Alias('install', inst)
269 # Add uninstall target.
270 env.Command('uninstall', None, Delete(projectdir), chdir = True)
271 Help(help_format % ("uninstall", "uninstall documentation"))
273 ## Add package builder.
274 #packageroot = "-".join([project_tag, release_tag])
275 #archive, package = env.Package(NAME = project_tag, VERSION = release,
276 # PACKAGEROOT = packageroot,
277 # PACKAGETYPE = pkgtype,
280 #env.AlwaysBuild(archive)
281 #env.AddPostAction(archive, Delete(packageroot))
282 #Help(help_format % ("package", "build documentation package"))
284 #env.Clean('all', archive)
286 # Add config settings to help.
287 Help("\nConfiguration variables:")
288 for line in config.GenerateHelpText(env).split("\n"):
291 # Save local configuration if required.
294 config.Save(cachefile, env)