Revert "bpo-30487: automatically create a venv and install Sphinx whe… · python/cpython@122fc13 (original) (raw)
`@@ -21,16 +21,21 @@ 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
``
`-
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.
`
``
24
`+
The easiest way to install these tools is to create a virtual environment and
`
``
25
`+
install the tools into there.
`
27
26
``
28
27
``
29
28
`Using make
`
30
29
`----------
`
31
30
``
32
``
`-
A Makefile has been prepared so that (on Unix), after you change into the
`
33
``
``Doc/`` directory you can simply run ::
``
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::
`
34
39
``
35
40
` make html
`
36
41
``
`@@ -39,17 +44,8 @@ look for instances of sphinxbuild and blurb installed on your process PATH
`
39
44
`(configurable with the SPHINXBUILD and BLURB variables).
`
40
45
``
41
46
`On Windows, we try to emulate the Makefile as closely as possible with a
`
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.
`
``
47
``make.bat`` file. If you need to specify the Python interpreter to use,
``
48
`+
set the PYTHON environment variable instead.
`
53
49
``
54
50
`Available make targets are:
`
55
51
``
`@@ -108,14 +104,11 @@ Available make targets are:
`
108
104
`Without make
`
109
105
`------------
`
110
106
``
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 ::
``
107
`+
First, install the tool dependencies from PyPI.
`
``
108
+
``
109
Then, from the ``Doc`` directory, run ::
114
110
``
115
``
`-
$ python3 -m venv venv
`
116
``
`-
$ source venv/bin/activate
`
117
``
`-
(venv) $ pip install Sphinx
`
118
``
`-
(venv) $ sphinx-build -b . build/
`
``
111
`+
sphinx-build -b . build/
`
119
112
``
120
113
``` where <builder> is one of html, text, latex, or htmlhelp (for explanations
```
121
114
`see the make targets above).
`