From 912bb57255e2eab4fb327d91d35cf8842edd7dad Mon Sep 17 00:00:00 2001 From: michael vincerra <37549381+mvincerx@users.noreply.github.com> Date: Thu, 21 Nov 2019 16:40:49 -0800 Subject: [PATCH] Add virtualenv option for contributors in README. (#927) Signed-off-by: Michael Vincerra Revise Makefile to enable make venv target and add instructions. Signed-off-by: Michael Vincerra Revises README.md and root-level Makefile target `make venv`. Signed-off-by: Michael Vincerra Revise venv target; revise README to simplify activation/deactivation. Signed-off-by: Michael Vincerra Revise syntax to emph markdown rendering. Signed-off-by: Michael Vincerra Fix formatting errors and make consistent ref to platforms. Signed-off-by: Michael Vincerra --- Makefile | 3 +- README.rst | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 84 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index cc811a48..bb3a8c22 100644 --- a/Makefile +++ b/Makefile @@ -34,7 +34,6 @@ clean: rm -rf venv venv: - virtualenv -p python$(PY_VERSION) venv; + virtualenv venv;\ source venv/bin/activate; \ pip3 install -r requirements.txt; - diff --git a/README.rst b/README.rst index 6eca594a..a6a3770c 100644 --- a/README.rst +++ b/README.rst @@ -67,6 +67,87 @@ If you want to build the documentation exactly as seen on the website, use ``make py`` followed by ``make htmlall``. This builds some external dependencies and all supported languages. +Use virtualenv +************** + +To develop documentation in a ``virtualenv``, use the ``venv`` target. +The Clear Linux\* OS documentation make target ``venv`` provides a +simple development environment that ensures that you have the +latest packages and that you manage Python versions separately. Use of the +``virtualenv`` requires **Python 3.6** or higher. For Windows examples below, use Powershell as an Administrator. + +The version of Python used to **create the virtual environment** is the +default python version **used in the virtual environment**. + +#. Verify ``pip`` is installed. A file path to pip should appear. + + * On Clear Linux OS and macOS\*: + + .. code-block:: bash + + which pip + + On Windows\* 10 OS: + + .. code-block:: bash + + pip --version + +#. If ``pip`` is not installed, install it. + + * On Clear Linux OS and macOS: + + .. code-block:: bash + + python3 -m pip install --user --upgrade pip + + * On Windows 10 OS: + + .. code-block:: bash + + py -m pip install --upgrade pip + + .. note:: + + This assumes Python was already added to your Windows path. + +Install virtualenv +------------------ + +#. Install ``virtualenv``. + + * On Clear Linux\* OS and macOS\*: + + .. code-block:: bash + + python3 -m pip install --user virtualenv + + * On Windows 10 OS: + + .. code-block:: bash + + py -m pip install --user virtualenv + +#. Create the ``virtualenv`` and install the required packages: + + .. code-block:: bash + + make venv + + #. Activate the ``venv``. + + .. code-block:: bash + + source venv/bin/activate + + Follow `Run the build`_ section to start developing documentation. + +#. Remove the ``venv`` when finished developing. + + .. code-block:: bash + + deactivate + Additional help *************** @@ -80,7 +161,8 @@ build before building again by running ``make clean``: make clean -This will completely remove the previous build output. +This will completely remove the previous build output, including artifacts +from the `make venv` target when done outside an active venv. Convenience script ==================