bpo-30487: automatically create a venv and install Sphinx when runnin… · python/cpython@d8d6b91 (original) (raw)
`@@ -21,21 +21,16 @@ tree but are maintained separately and are available from
`
21
21
`` * Sphinx <https://pypi.org/project/Sphinx/>_
``
22
22
`` * blurb <https://pypi.org/project/blurb/>_
``
23
23
``
24
``
`-
The easiest way to install these tools is to create a virtual environment and
`
25
``
`-
install the tools into there.
`
``
24
`+
You could manually create a virtual environment and install them, but there is
`
``
25
a ``Makefile`` already set up to do this for you, as long as you have a working
``
26
`+
Python 3 interpreter available.
`
26
27
``
27
28
``
28
29
`Using make
`
29
30
`----------
`
30
31
``
31
``
`-
To get started on UNIX, you can create a virtual environment with the command ::
`
32
``
-
33
``
`-
make venv
`
34
``
-
35
``
`-
That will install all the tools necessary to build the documentation. Assuming
`
36
``
the virtual environment was created in the ``env`` directory (the default;
37
``
`-
configurable with the VENVDIR variable), you can run the following command to
`
38
``
`-
build the HTML output files::
`
``
32
`+
A Makefile has been prepared so that (on Unix), after you change into the
`
``
33
``Doc/`` directory you can simply run ::
39
34
``
40
35
` make html
`
41
36
``
`@@ -44,8 +39,17 @@ look for instances of sphinxbuild and blurb installed on your process PATH
`
44
39
`(configurable with the SPHINXBUILD and BLURB variables).
`
45
40
``
46
41
`On Windows, we try to emulate the Makefile as closely as possible with a
`
47
``
``make.bat`` file. If you need to specify the Python interpreter to use,
48
``
`-
set the PYTHON environment variable instead.
`
``
42
``make.bat`` file.
``
43
+
``
44
To use a Python interpreter that's not called ``python3``, use the standard
``
45
`+
way to set Makefile variables, using e.g. ::
`
``
46
+
``
47
`+
make html PYTHON=python
`
``
48
+
``
49
`+
On Windows, set the PYTHON environment variable instead.
`
``
50
+
``
51
To use a specific sphinx-build (something other than ``sphinx-build``), set
``
52
`+
the SPHINXBUILD variable.
`
49
53
``
50
54
`Available make targets are:
`
51
55
``
`@@ -104,11 +108,14 @@ Available make targets are:
`
104
108
`Without make
`
105
109
`------------
`
106
110
``
107
``
`-
First, install the tool dependencies from PyPI.
`
108
``
-
109
``
Then, from the ``Doc`` directory, run ::
``
111
`+
Install the Sphinx package and its dependencies from PyPI. In this situation,
`
``
112
`+
you'll have to create a virtual environment manually, and install Sphinx into
`
``
113
it. Change into the ``Doc`` directory and run ::
110
114
``
111
``
`-
sphinx-build -b . build/
`
``
115
`+
$ python3 -m venv venv
`
``
116
`+
$ source venv/bin/activate
`
``
117
`+
(venv) $ pip install Sphinx
`
``
118
`+
(venv) $ sphinx-build -b . build/
`
112
119
``
113
120
``` where <builder> is one of html, text, latex, or htmlhelp (for explanations
```
114
121
`see the make targets above).
`