From 62d6d13132e7edebceac03af183123ac2dfaa71a Mon Sep 17 00:00:00 2001
From: Eric Cousineau <eric.cousineau@tri.global>
Date: Sat, 11 Jul 2020 16:26:30 -0400
Subject: [PATCH] install: Expose test requirements, encourage use of
 virtualenv

- Use `setuputils.setup(..., extras_require)`
- Organize imports according to PEP8 (builtin, 3rd party, then 1st party)
---
 .github/workflows/tests.yml |  7 ++-----
 .gitignore                  |  1 +
 docs/conf.py                |  2 +-
 docs/documentation.rst      |  8 +++++---
 docs/install.rst            | 18 +++++++++++++++++-
 setup.py                    | 14 ++++++++++++++
 unittests/pep8_tester.py    |  3 ++-
 7 files changed, 42 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 8b2b7375..2af2dbee 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -83,15 +83,12 @@ jobs:
       - name: Setup castxml config
         if: matrix.compiler == 'gcc' && matrix.version == '7'
         run: mv unittests/configs/gcc7.cfg unittests/xml_generator.cfg;
-      - name: Setup Python test libs
+      - name: Install Python lib and test libs
         run: |
-          pip install coveralls
-          pip install coverage
-          pip install pycodestyle
+          pip install .[test]
       - name: Run tests
         run: |
           export PATH=~/castxml/bin:$PATH
-          python setup.py install
           coverage run -m unittests.test_all
           coverage combine
       - name: Upload coverage to Codecov
diff --git a/.gitignore b/.gitignore
index f026e1ab..e849f161 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,3 +16,4 @@ docs/examples/caching/example.hpp.xml
 test_cost.log
 docs/apidocs
 htmlcov
+/venv/
diff --git a/docs/conf.py b/docs/conf.py
index 2ded1089..0c8c7bb7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -22,7 +22,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('.') + "/../")
 
-from ..release_utils import utils  # nopep8
+from release_utils import utils  # nopep8
 
 # -- General configuration ------------------------------------------------
 
diff --git a/docs/documentation.rst b/docs/documentation.rst
index 2fd9fd45..fb65b32d 100644
--- a/docs/documentation.rst
+++ b/docs/documentation.rst
@@ -7,15 +7,17 @@ Building the documentation locally
 You can build the documentation yourself. In order for this to work you need
 sphinx doc (http://sphinx-doc.org) and the readthedocs theme:
 
-    pip install sphinx
+.. code-block:: shell
 
-    pip install sphinx_rtd_theme
+  pip install .[docs]
 
 Then just run the following command in the root folder:
 
+.. code-block:: shell
+
   make html
 
-This will build the documentation locally in the `docs/_build/html` folder.
+This will build the documentation locally in the ``docs/_build/html`` folder.
 
 For each commit on the master and develop branches, the documentation is
 automatically built and can be found here: https://readthedocs.org/projects/pygccxml/
diff --git a/docs/install.rst b/docs/install.rst
index 172f0f33..230ef45f 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -18,12 +18,28 @@ Installation of pygccxml
 
 You can use pip to install pygccxml:
 
-  pip install pygccxml
+.. code-block:: shell
+
+    pip install pygccxml
 
 To install from source, you can use the usual procedure:
 
+.. code-block:: shell
+
   python setup.py install
 
+For development
+%%%%%%%%%%%%%%%
+
+You should use a ``virtualenv`` when possible. Example recipe:
+
+.. code-block:: shell
+
+  cd pygccxml  # git root
+  python -m virtualenv ./venv
+  source ./venv/bin/activate
+  pip install --editable .[test]
+
 GCC-XML (Legacy)
 ----------------
 
diff --git a/setup.py b/setup.py
index 23e4fd34..a87a6283 100644
--- a/setup.py
+++ b/setup.py
@@ -9,6 +9,16 @@
 
 version = utils.find_version("../pygccxml/__init__.py")
 
+requirements_test = {
+  "coverage",
+  "coveralls",
+  "pycodestyle",
+}
+requirements_docs = {
+  "sphinx",
+  "sphinx_rtd_theme",
+}
+
 setup(name="pygccxml",
       version=version,
       author="Roman Yakovenko",
@@ -25,6 +35,10 @@
                 "pygccxml.declarations",
                 "pygccxml.parser",
                 "pygccxml.utils"],
+      extras_require={
+          "test": list(requirements_test),
+          "docs": list(requirements_docs),
+      },
       classifiers=[
           "Development Status :: 5 - Production/Stable",
           "Environment :: Console",
diff --git a/unittests/pep8_tester.py b/unittests/pep8_tester.py
index a7a936b4..3405de42 100644
--- a/unittests/pep8_tester.py
+++ b/unittests/pep8_tester.py
@@ -4,10 +4,11 @@
 # See http://www.boost.org/LICENSE_1_0.txt
 
 import os
-import pycodestyle
 import unittest
 import fnmatch
 
+import pycodestyle
+
 
 class Test(unittest.TestCase):