Update makefile and batchfile for Sphinx
authorHarmon <Harmon758@gmail.com>
Mon, 6 Jan 2020 10:11:41 +0000 (04:11 -0600)
committerHarmon <Harmon758@gmail.com>
Mon, 6 Jan 2020 10:11:41 +0000 (04:11 -0600)
docs/Makefile
docs/make.bat

index 5d97e1a88909553ef1588215fa1ef2eef13c4d99..d4bb2cbb9eddb1bb1b4f366623044af8e4830919 100644 (file)
@@ -1,99 +1,20 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
-
+# Put it first so that "make" without argument is like "make help".
 help:
-       @echo "Please use \`make <target>' where <target> is one of"
-       @echo "  html      to make standalone HTML files"
-       @echo "  dirhtml   to make HTML files named index.html in directories"
-       @echo "  pickle    to make pickle files"
-       @echo "  json      to make JSON files"
-       @echo "  htmlhelp  to make HTML files and a HTML help project"
-       @echo "  qthelp    to make HTML files and a qthelp project"
-       @echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-       @echo "  changes   to make an overview of all changed/added/deprecated items"
-       @echo "  linkcheck to check all external links for integrity"
-       @echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-       -rm -rf $(BUILDDIR)/*
-
-html:
-       mkdir -p $(BUILDDIR)/html
-       $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-       @echo
-       @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-       mkdir -p $(BUILDDIR)/dirhtml
-       $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-       @echo
-       @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-pickle:
-       mkdir -p $(BUILDDIR)/pickle
-       $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-       @echo
-       @echo "Build finished; now you can process the pickle files."
-
-json:
-       mkdir -p $(BUILDDIR)/json
-       $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-       @echo
-       @echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-       mkdir -p $(BUILDDIR)/htmlhelp
-       $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-       @echo
-       @echo "Build finished; now you can run HTML Help Workshop with the" \
-             ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-       mkdir -p $(BUILDDIR)/qthelp
-       $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-       @echo
-       @echo "Build finished; now you can run "qcollectiongenerator" with the" \
-             ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-       @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/tweepy.qhcp"
-       @echo "To view the help file:"
-       @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/tweepy.qhc"
-
-latex:
-       mkdir -p $(BUILDDIR)/latex
-       $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-       @echo
-       @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-       @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-             "run these through (pdf)latex."
-
-changes:
-       mkdir -p $(BUILDDIR)/changes
-       $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-       @echo
-       @echo "The overview file is in $(BUILDDIR)/changes."
+       @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-linkcheck:
-       mkdir -p $(BUILDDIR)/linkcheck
-       $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-       @echo
-       @echo "Link check complete; look for any errors in the above output " \
-             "or in $(BUILDDIR)/linkcheck/output.txt."
+.PHONY: help Makefile
 
-doctest:
-       mkdir -p $(BUILDDIR)/doctest
-       $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-       @echo "Testing of doctests in the sources finished, look at the " \
-             "results in $(BUILDDIR)/doctest/output.txt."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+       @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
index 10adbcd817741353e5ee9fa7c27624b6fd3ac645..922152e96a04a242e6fc40f124261d74890617d8 100644 (file)
 @ECHO OFF
 
+pushd %~dp0
+
 REM Command file for Sphinx documentation
 
-set SPHINXBUILD=sphinx-build
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-if NOT "%PAPER%" == "" (
-       set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+if "%SPHINXBUILD%" == "" (
+       set SPHINXBUILD=sphinx-build
 )
+set SOURCEDIR=.
+set BUILDDIR=_build
 
 if "%1" == "" goto help
 
-if "%1" == "help" (
-       :help
-       echo.Please use `make ^<target^>` where ^<target^> is one of
-       echo.  html      to make standalone HTML files
-       echo.  dirhtml   to make HTML files named index.html in directories
-       echo.  pickle    to make pickle files
-       echo.  json      to make JSON files
-       echo.  htmlhelp  to make HTML files and a HTML help project
-       echo.  qthelp    to make HTML files and a qthelp project
-       echo.  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
-       echo.  changes   to make an overview over all changed/added/deprecated items
-       echo.  linkcheck to check all external links for integrity
-       echo.  doctest   to run all doctests embedded in the documentation if enabled
-       goto end
-)
-
-if "%1" == "clean" (
-       for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
-       del /q /s %BUILDDIR%\*
-       goto end
-)
-
-if "%1" == "html" (
-       %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
-       echo.
-       echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-       goto end
-)
-
-if "%1" == "dirhtml" (
-       %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
        echo.
-       echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
-       goto end
-)
-
-if "%1" == "pickle" (
-       %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+       echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+       echo.installed, then set the SPHINXBUILD environment variable to point
+       echo.to the full path of the 'sphinx-build' executable. Alternatively you
+       echo.may add the Sphinx directory to PATH.
        echo.
-       echo.Build finished; now you can process the pickle files.
-       goto end
+       echo.If you don't have Sphinx installed, grab it from
+       echo.http://sphinx-doc.org/
+       exit /b 1
 )
 
-if "%1" == "json" (
-       %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
-       echo.
-       echo.Build finished; now you can process the JSON files.
-       goto end
-)
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
 
-if "%1" == "htmlhelp" (
-       %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
-       echo.
-       echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
-       goto end
-)
-
-if "%1" == "qthelp" (
-       %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
-       echo.
-       echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
-       echo.^> qcollectiongenerator %BUILDDIR%\qthelp\tweepy.qhcp
-       echo.To view the help file:
-       echo.^> assistant -collectionFile %BUILDDIR%\qthelp\tweepy.ghc
-       goto end
-)
-
-if "%1" == "latex" (
-       %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-       echo.
-       echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
-       goto end
-)
-
-if "%1" == "changes" (
-       %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
-       echo.
-       echo.The overview file is in %BUILDDIR%/changes.
-       goto end
-)
-
-if "%1" == "linkcheck" (
-       %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
-       echo.
-       echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
-       goto end
-)
-
-if "%1" == "doctest" (
-       %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-       echo.
-       echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-       goto end
-)
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
+popd