Build in a virtual environment on Windows (python#267) (python#268)

jeff5 · ezio-melotti · commit 3d92a7ee0bc1 · 2017-10-01T05:04:12.000+02:00
* Build in a virtual environment on Windows (pythonGH-267) Add to the Windows build script a clause to create and use a virtual environment and install Sphinx there, comparable with the Unix Makefile. The user may suppress this behaviour by defining a her preferred command in the environment variable SPHINXBUILD, as before. * Simplify wording and add comment following review. * Always build relative to the directory containing make.bat Whatever the current directory when invoked, the build takes place into _build/... in the directory that contains make.bat, and returns to the invocation directory. * Properly escape parentheses in the help text. Previously this disabled subsequent build targets by making "goto end" accidentally unconditional. We also describe the "check" target.
diff --git a/docquality.rst b/docquality.rst
@@ -86,12 +86,18 @@ To build the devguide, some additional dependencies are required (most
 importantly, `Sphinx`_), and the standard way to install dependencies in
 Python projects is to create a virtualenv, and then install dependencies from
 a ``requirements.txt`` file. For your convenience, this is all *automated for
-you* and all you have to do to build the devguide is run::
+you*. To build the devguide on a Unix-like system use::
 
     $ make html
 
-in the checkout directory, which will write the files to the ``_build/html``
-directory.  Note that ``make check`` is automatically run when
+in the checkout directory. On Windows use:
+
+..  code-block:: doscon
+
+    > .\make html
+
+You will find the generated files in ``_build/html``.
+Note that ``make check`` is automatically run when
 you submit a :doc:`pull request <pullrequest>`, so you should make
 sure that it runs without errors.
 
diff --git a/make.bat b/make.bat
@@ -2,22 +2,24 @@
 
 REM Command file for Sphinx documentation
 
+setlocal
+
+pushd %~dp0
+
 if "%PYTHON%" == "" (
 	set PYTHON=py -3
 )
-if "%SPHINXBUILD%" == "" (
-	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 "%1" == "" goto help
 if "%1" == "check" goto check
 if "%1" == "serve" goto serve
 
+if "%1" == "" goto help
 if "%1" == "help" (
 	:help
 	echo.Please use `make ^<target^>` where ^<target^> is one of
@@ -36,8 +38,8 @@ if "%1" == "help" (
 	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
-	echo.  check
-	echo.  serve      to serve devguide on the localhost (8000)
+	echo.  check      to check for stylistic and formal issues using rstlint
+	echo.  serve      to serve devguide on the localhost ^(8000^)
 	goto end
 )
 
@@ -47,6 +49,21 @@ if "%1" == "clean" (
 	goto end
 )
 
+rem Targets other than "clean", "check", "serve", "help", or "" need the
+rem Sphinx build command, which the user may define via SPHINXBUILD.
+
+if not defined SPHINXBUILD (
+	rem If it is not defined, we build in a virtual environment
+	if not exist venv (
+		echo.    Setting up the virtual environment
+		%PYTHON% -m venv venv
+		echo.    Installing requirements
+		venv\Scripts\python -m pip install -r requirements.txt
+	)
+	set PYTHON=venv\Scripts\python
+	set SPHINXBUILD=venv\Scripts\sphinx-build
+)
+
 if "%1" == "html" (
 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
 	if errorlevel 1 exit /b 1
@@ -183,3 +200,5 @@ cmd /C %PYTHON% tools\serve.py %BUILDDIR%\html
 goto end
 
 :end
+popd
+endlocal
