mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Make mode: refactor using a class and add source dir to the makefile
This commit is contained in:
Georg Brandl
parent
b74759c67d
commit
1653c5d242
18
doc/Makefile
18
doc/Makefile
@ -5,20 +5,14 @@
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = python ../sphinx-build.py
|
||||
SPHINXPROJ = sphinx
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# User-friendly check for sphinx-build
|
||||
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
|
||||
$(error \
|
||||
The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx \
|
||||
installed, then set the SPHINXBUILD environment variable to point \
|
||||
to the full path of the '$(SPHINXBUILD)' executable. Alternatively you \
|
||||
can add the directory with the executable to your PATH. \
|
||||
If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
|
||||
endif
|
||||
|
||||
# Has to be explicit, otherwise we don't get "make" without targets right.
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%:
|
||||
@$(SPHINXBUILD) -M $@ "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
@ -26,15 +26,6 @@ from sphinx.util.console import bold, blue
|
||||
|
||||
proj_name = os.getenv('SPHINXPROJ', '<project>')
|
||||
|
||||
def build_clean(builddir, opts):
|
||||
if not path.exists(builddir):
|
||||
return
|
||||
elif not path.isdir(builddir):
|
||||
print "Error: %r is not a directory!" % builddir
|
||||
return 1
|
||||
print "removing everything under %r..." % builddir
|
||||
for item in os.listdir(builddir):
|
||||
shutil.rmtree(path.join(builddir, item))
|
||||
|
||||
BUILDERS = [
|
||||
("", "html", "to make standalone HTML files"),
|
||||
@ -62,179 +53,200 @@ BUILDERS = [
|
||||
("", "coverage", "to run coverage check of the documentation (if enabled)"),
|
||||
]
|
||||
|
||||
def build_help(builddir, opts):
|
||||
print bold("Sphinx v%s" % sphinx.__version__)
|
||||
print "Please use `make %s' where %s is one of" % ((blue('target'),)*2)
|
||||
for osname, bname, description in BUILDERS:
|
||||
if not osname or os.name == osname:
|
||||
print ' %s %s' % (blue(bname.ljust(10)), description)
|
||||
|
||||
class Make(object):
|
||||
|
||||
def build_html(builddir, opts):
|
||||
if run_generic_build('html', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The HTML pages are in %s.' % path.join(builddir, 'html')
|
||||
def __init__(self, srcdir, builddir, opts):
|
||||
self.srcdir = srcdir
|
||||
self.builddir = builddir
|
||||
self.opts = opts
|
||||
|
||||
def build_dirhtml(builddir, opts):
|
||||
if run_generic_build('dirhtml', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The HTML pages are in %s.' % path.join(builddir, 'dirhtml')
|
||||
def builddir_join(self, *comps):
|
||||
return path.join(self.builddir, *comps)
|
||||
|
||||
def build_singlehtml(builddir, opts):
|
||||
if run_generic_build('singlehtml', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The HTML page is in %s.' % path.join(builddir, 'singlehtml')
|
||||
def build_clean(self):
|
||||
if not path.exists(self.builddir):
|
||||
return
|
||||
elif not path.isdir(self.builddir):
|
||||
print "Error: %r is not a directory!" % self.builddir
|
||||
return 1
|
||||
print "Removing everything under %r..." % self.builddir
|
||||
for item in os.listdir(self.builddir):
|
||||
shutil.rmtree(self.builddir_join(item))
|
||||
|
||||
def build_pickle(builddir, opts):
|
||||
if run_generic_build('pickle', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished; now you can process the pickle files.'
|
||||
def build_help(self):
|
||||
print bold("Sphinx v%s" % sphinx.__version__)
|
||||
print "Please use `make %s' where %s is one of" % ((blue('target'),)*2)
|
||||
for osname, bname, description in BUILDERS:
|
||||
if not osname or os.name == osname:
|
||||
print ' %s %s' % (blue(bname.ljust(10)), description)
|
||||
|
||||
def build_json(builddir, opts):
|
||||
if run_generic_build('json', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished; now you can process the JSON files.'
|
||||
def build_html(self):
|
||||
if self.run_generic_build('html') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The HTML pages are in %s.' % self.builddir_join('html')
|
||||
|
||||
def build_htmlhelp(builddir, opts):
|
||||
if run_generic_build('htmlhelp', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print ('Build finished; now you can run HTML Help Workshop with the '
|
||||
'.hhp project file in %s.') % path.join(builddir, 'htmlhelp')
|
||||
def build_dirhtml(self):
|
||||
if self.run_generic_build('dirhtml') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The HTML pages are in %s.' % self.builddir_join('dirhtml')
|
||||
|
||||
def build_qthelp(builddir, opts):
|
||||
if run_generic_build('qthelp', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print ('Build finished; now you can run "qcollectiongenerator" with the '
|
||||
'.qhcp project file in %s, like this:') % path.join(builddir, 'qthelp')
|
||||
print '$ qcollectiongenerator %s.qhcp' % path.join(builddir, 'qthelp', proj_name)
|
||||
print 'To view the help file:'
|
||||
print '$ assistant -collectionFile %s.qhc' % path.join(builddir, 'qthelp', proj_name)
|
||||
def build_singlehtml(self):
|
||||
if self.run_generic_build('singlehtml') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The HTML page is in %s.' % self.builddir_join('singlehtml')
|
||||
|
||||
def build_devhelp(builddir, opts):
|
||||
if run_generic_build('devhelp', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print "Build finished."
|
||||
print "To view the help file:"
|
||||
print "$ mkdir -p $HOME/.local/share/devhelp/" + proj_name
|
||||
print "$ ln -s %s $HOME/.local/share/devhelp/%s" % \
|
||||
(path.join(builddir, 'devhelp'), proj_name)
|
||||
print "$ devhelp"
|
||||
def build_pickle(self):
|
||||
if self.run_generic_build('pickle') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished; now you can process the pickle files.'
|
||||
|
||||
def build_epub(builddir, opts):
|
||||
if run_generic_build('epub', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The ePub file is in %s.' % path.join(builddir, 'epub')
|
||||
def build_json(self):
|
||||
if self.run_generic_build('json') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished; now you can process the JSON files.'
|
||||
|
||||
def build_latex(builddir, opts):
|
||||
if run_generic_build('latex', builddir, opts) > 0:
|
||||
return 1
|
||||
print "Build finished; the LaTeX files are in %s." % path.join(builddir, 'latex')
|
||||
if os.name == 'posix':
|
||||
print "Run `make' in that directory to run these through (pdf)latex"
|
||||
print "(use `make latexpdf' here to do that automatically)."
|
||||
def build_htmlhelp(self):
|
||||
if self.run_generic_build('htmlhelp') > 0:
|
||||
return 1
|
||||
print
|
||||
print ('Build finished; now you can run HTML Help Workshop with the '
|
||||
'.hhp project file in %s.') % self.builddir_join('htmlhelp')
|
||||
|
||||
def build_latexpdf(builddir, opts):
|
||||
if run_generic_build('latex', builddir, opts) > 0:
|
||||
return 1
|
||||
os.system('make -C %s all-pdf' % path.join(builddir, 'latex'))
|
||||
def build_qthelp(self):
|
||||
if self.run_generic_build('qthelp') > 0:
|
||||
return 1
|
||||
print
|
||||
print ('Build finished; now you can run "qcollectiongenerator" with the '
|
||||
'.qhcp project file in %s, like this:') % self.builddir_join('qthelp')
|
||||
print '$ qcollectiongenerator %s.qhcp' % self.builddir_join('qthelp', proj_name)
|
||||
print 'To view the help file:'
|
||||
print '$ assistant -collectionFile %s.qhc' % self.builddir_join('qthelp', proj_name)
|
||||
|
||||
def build_latexpdfja(builddir, opts):
|
||||
if run_generic_build('latex', builddir, opts) > 0:
|
||||
return 1
|
||||
os.system('make -C %s all-pdf-ja' % path.join(builddir, 'latex'))
|
||||
def build_devhelp(self):
|
||||
if self.run_generic_build('devhelp') > 0:
|
||||
return 1
|
||||
print
|
||||
print "Build finished."
|
||||
print "To view the help file:"
|
||||
print "$ mkdir -p $HOME/.local/share/devhelp/" + proj_name
|
||||
print "$ ln -s %s $HOME/.local/share/devhelp/%s" % \
|
||||
(self.builddir_join('devhelp'), proj_name)
|
||||
print "$ devhelp"
|
||||
|
||||
def build_text(builddir, opts):
|
||||
if run_generic_build('text', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The text files are in %s.' % path.join(builddir, 'text')
|
||||
def build_epub(self):
|
||||
if self.run_generic_build('epub') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The ePub file is in %s.' % self.builddir_join('epub')
|
||||
|
||||
def build_texinfo(builddir, opts):
|
||||
if run_generic_build('texinfo', builddir, opts) > 0:
|
||||
return 1
|
||||
print "Build finished; the Texinfo files are in %s." % path.join(builddir, 'texinfo')
|
||||
if os.name == 'posix':
|
||||
print "Run `make' in that directory to run these through makeinfo"
|
||||
print "(use `make info' here to do that automatically)."
|
||||
def build_latex(self):
|
||||
if self.run_generic_build('latex') > 0:
|
||||
return 1
|
||||
print "Build finished; the LaTeX files are in %s." % self.builddir_join('latex')
|
||||
if os.name == 'posix':
|
||||
print "Run `make' in that directory to run these through (pdf)latex"
|
||||
print "(use `make latexpdf' here to do that automatically)."
|
||||
|
||||
def build_info(builddir, opts):
|
||||
if run_generic_build('texinfo', builddir, opts) > 0:
|
||||
return 1
|
||||
os.system('make -C %s info' % path.join(builddir, 'texinfo'))
|
||||
def build_latexpdf(self):
|
||||
if self.run_generic_build('latex') > 0:
|
||||
return 1
|
||||
os.system('make -C %s all-pdf' % self.builddir_join('latex'))
|
||||
|
||||
def build_gettext(builddir, opts):
|
||||
dtdir = path.join(builddir, 'gettext', '.doctrees')
|
||||
if run_generic_build('gettext', builddir, opts, doctreedir=dtdir) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The message catalogs are in %s.' % path.join(builddir, 'gettext')
|
||||
def build_latexpdfja(self):
|
||||
if self.run_generic_build('latex') > 0:
|
||||
return 1
|
||||
os.system('make -C %s all-pdf-ja' % self.builddir_join('latex'))
|
||||
|
||||
def build_changes(builddir, opts):
|
||||
if run_generic_build('changes', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The overview file is in %s.' % path.join(builddir, 'changes')
|
||||
def build_text(self):
|
||||
if self.run_generic_build('text') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The text files are in %s.' % self.builddir_join('text')
|
||||
|
||||
def build_linkcheck(builddir, opts):
|
||||
res = run_generic_build('linkcheck', builddir, opts)
|
||||
print
|
||||
print ('Link check complete; look for any errors in the above output '
|
||||
'or in %s.') % path.join(builddir, 'linkcheck', 'output.txt')
|
||||
return res
|
||||
def build_texinfo(self):
|
||||
if self.run_generic_build('texinfo') > 0:
|
||||
return 1
|
||||
print "Build finished; the Texinfo files are in %s." % self.builddir_join('texinfo')
|
||||
if os.name == 'posix':
|
||||
print "Run `make' in that directory to run these through makeinfo"
|
||||
print "(use `make info' here to do that automatically)."
|
||||
|
||||
def build_doctest(builddir, opts):
|
||||
res = run_generic_build('doctest', builddir, opts)
|
||||
print ("Testing of doctests in the sources finished, look at the "
|
||||
"results in %s." % path.join(builddir, 'doctest', 'output.txt'))
|
||||
return res
|
||||
def build_info(self):
|
||||
if self.run_generic_build('texinfo') > 0:
|
||||
return 1
|
||||
os.system('make -C %s info' % self.builddir_join('texinfo'))
|
||||
|
||||
def build_coverage(builddir, opts):
|
||||
if run_generic_build('coverage', builddir, opts) > 0:
|
||||
print "Has the coverage extension been enabled?"
|
||||
return 1
|
||||
print
|
||||
print ("Testing of coverage in the sources finished, look at the "
|
||||
"results in %s." % path.join(builddir, 'coverage'))
|
||||
def build_gettext(self):
|
||||
dtdir = self.builddir_join('gettext', '.doctrees')
|
||||
if self.run_generic_build('gettext', doctreedir=dtdir) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The message catalogs are in %s.' % self.builddir_join('gettext')
|
||||
|
||||
def build_xml(builddir, opts):
|
||||
if run_generic_build('xml', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The XML files are in %s.' % path.join(builddir, 'xml')
|
||||
def build_changes(self):
|
||||
if self.run_generic_build('changes') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The overview file is in %s.' % self.builddir_join('changes')
|
||||
|
||||
def build_pseudoxml(builddir, opts):
|
||||
if run_generic_build('pseudoxml', builddir, opts) > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The pseudo-XML files are in %s.' % path.join(builddir, 'pseudoxml')
|
||||
def build_linkcheck(self):
|
||||
res = self.run_generic_build('linkcheck')
|
||||
print
|
||||
print ('Link check complete; look for any errors in the above output '
|
||||
'or in %s.') % self.builddir_join('linkcheck', 'output.txt')
|
||||
return res
|
||||
|
||||
def build_doctest(self):
|
||||
res = self.run_generic_build('doctest')
|
||||
print ("Testing of doctests in the sources finished, look at the "
|
||||
"results in %s." % self.builddir_join('doctest', 'output.txt'))
|
||||
return res
|
||||
|
||||
def run_generic_build(builder, builddir, opts, doctreedir=None):
|
||||
# compatibility with old Makefile
|
||||
papersize = os.getenv('PAPER', '')
|
||||
if papersize in ('a4', 'letter'):
|
||||
opts.extend(['-D', 'latex_paper_size=' + papersize])
|
||||
if doctreedir is None:
|
||||
doctreedir = path.join(builddir, 'doctrees')
|
||||
return call([sys.executable, sys.argv[0], '-b', builder,
|
||||
'-d', doctreedir, '.', path.join(builddir, builder)] + opts)
|
||||
def build_coverage(self):
|
||||
if self.run_generic_build('coverage') > 0:
|
||||
print "Has the coverage extension been enabled?"
|
||||
return 1
|
||||
print
|
||||
print ("Testing of coverage in the sources finished, look at the "
|
||||
"results in %s." % self.builddir_join('coverage'))
|
||||
|
||||
def build_xml(self):
|
||||
if self.run_generic_build('xml') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The XML files are in %s.' % self.builddir_join('xml')
|
||||
|
||||
def build_pseudoxml(self):
|
||||
if self.run_generic_build('pseudoxml') > 0:
|
||||
return 1
|
||||
print
|
||||
print 'Build finished. The pseudo-XML files are in %s.' % self.builddir_join('pseudoxml')
|
||||
|
||||
def run_generic_build(self, builder, doctreedir=None):
|
||||
# compatibility with old Makefile
|
||||
papersize = os.getenv('PAPER', '')
|
||||
opts = self.opts
|
||||
if papersize in ('a4', 'letter'):
|
||||
opts.extend(['-D', 'latex_paper_size=' + papersize])
|
||||
if doctreedir is None:
|
||||
doctreedir = self.builddir_join('doctrees')
|
||||
return call([sys.executable, sys.argv[0], '-b', builder,
|
||||
'-d', doctreedir, self.srcdir, self.builddir_join(builder)] + opts)
|
||||
|
||||
|
||||
def run_make_mode(args):
|
||||
if len(args) < 2:
|
||||
print >>sys.stderr, ('Error: at least two arguments (builder, build '
|
||||
'dir) are required.')
|
||||
if len(args) < 3:
|
||||
print >>sys.stderr, ('Error: at least 3 arguments (builder, source '
|
||||
'dir, build dir) are required.')
|
||||
return 1
|
||||
make = Make(args[1], args[2], args[3:])
|
||||
run_method = 'build_' + args[0]
|
||||
if run_method in globals():
|
||||
return globals()[run_method](args[1], args[2:])
|
||||
return run_generic_build(args[0], args[1], args[2:])
|
||||
if hasattr(make, run_method):
|
||||
return getattr(make, run_method)()
|
||||
return make.run_generic_build(args[0])
|
||||
|
||||
@ -839,16 +839,17 @@ if "%%1" == "pseudoxml" (
|
||||
|
||||
# This will become the Makefile template for Sphinx 1.5.
|
||||
MAKEFILE_NEW = u'''\
|
||||
# Makefile for Sphinx documentation
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXPROJ = %(project_fn)s
|
||||
SOURCEDIR = %(rsrcdir)s
|
||||
BUILDDIR = %(rbuilddir)s
|
||||
|
||||
# User-friendly check for sphinx-build
|
||||
# User-friendly check for sphinx-build.
|
||||
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
|
||||
$(error \
|
||||
The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx \
|
||||
@ -860,11 +861,14 @@ endif
|
||||
|
||||
# Has to be explicit, otherwise we don't get "make" without targets right.
|
||||
help:
|
||||
\t@$(SPHINXBUILD) -M help "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
\t@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
# Catch-all target using the new "make mode" option.
|
||||
# You can add custom targets here.
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%:
|
||||
\t@$(SPHINXBUILD) -M $@ "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
\t@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
'''
|
||||
|
||||
# This will become the make.bat template for Sphinx 1.5.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user