From 1653c5d242e06453bcf8adbc136cd30614935acb Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 19 Jan 2014 16:23:23 +0100 Subject: [PATCH] Make mode: refactor using a class and add source dir to the makefile --- doc/Makefile | 18 +-- sphinx/make_mode.py | 322 ++++++++++++++++++++++--------------------- sphinx/quickstart.py | 14 +- 3 files changed, 182 insertions(+), 172 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index d799c3658..8bc59724e 100644 --- a/doc/Makefile +++ b/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) diff --git a/sphinx/make_mode.py b/sphinx/make_mode.py index c8a2eae5f..24de6b286 100644 --- a/sphinx/make_mode.py +++ b/sphinx/make_mode.py @@ -26,15 +26,6 @@ from sphinx.util.console import bold, blue proj_name = os.getenv('SPHINXPROJ', '') -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]) diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 7ce3ad848..d9449f749 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -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.