NOBUG: Improve documentation

tkruse · tkruse · commit 69a4188b15d8 · 2019-09-16T13:08:08.000+09:00
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -29,11 +29,31 @@ Non-Goals:
 Development
 -----------
 
+For many tasks, it is okay to just develop using a single installed python version. But if you need to test/debug the project in multiple python versions, you need to install those version::
+
+1. (Optional) Install multiple python versions
+
+   1. (Optional) Install [pyenv](https://github.com/pyenv/pyenv-installer) to manage python versions
+   2. (Optional) Using pyenv, install the python versions used in testing::
+
+        pyenv install 2.7.16
+        pyenv install 3.6.8
+
+It may be okay to run and test python against locally installed libraries, but if you need to have a consistent build, it is recommended to manage your environment using virtualenv: [virtualenv](https://virtualenv.pypa.io/en/latest/ ), [virtualenvwrapper](https://pypi.org/project/virtualenvwrapper/ ):
+
+1. (Optional) Setup a local virtual environment with all necessary tools and libraries::
+
+      mkvirtualenv cpplint [-p /usr/bin/python3]
+      pip install .[dev]
+
+Alternatively you can locally install patches like this::
+
+    pip install --user -e .[dev]
+
 You can setup your local environment for developing patches for cpplint like this:
 
 .. code-block:: bash
 
-    pip install --user -e .[dev]
     ./setup.py lint
     ./setup.py style
     ./setup.py test
@@ -53,12 +73,12 @@ To release a new version:
     git commit -m "Releasing x.y.z"
     git add cpplint.py changelog.rst
     # test-release (on env by mkvirtualenv -p /usr/bin/python3)
-    pip install --upgrade setuptools wheels twine
+    pip install --upgrade setuptools wheel twine
     twine upload --repository testpypi dist/*
     # ... Check website and downloads from https://test.pypi.org/project/cpplint/
     # Actual release
     python3 setup.py sdist bdist_wheel
-    twine upload  dist/*
+    twine upload dist/*
     git tag x.y.z
     git push
     git push --tags
diff --git a/setup.py b/setup.py
@@ -6,6 +6,10 @@
 import cpplint as cpplint
 
 class Cmd(Command):
+    '''
+    Superclass for other commands to run via setup.py, declared in setup.cfg.
+    These commands will auto-install setup_requires in a temporary folder.
+    '''
     user_options = [
       ('executable', 'e', 'The executable to use for the command')
     ]
@@ -21,6 +25,7 @@ def execute(self, *k):
 
 
 class Lint(Cmd):
+    '''run with python setup.py lint'''
     description = 'Run linting of the code'
     user_options = Cmd.user_options + [
       ('jobs', 'j', 'Use multiple processes to speed up the linting')
