Merge "Add pre-commit"

2 files changed, 69 insertions, 13 deletions

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 00000000..f91d10b7
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,29 @@
+---
+default_language_version:
+  # force all unspecified python hooks to run python3
+  python: python3
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+        args: ['--fix', 'lf']
+        exclude: '.*\.(svg)$'
+      - id: check-byte-order-marker
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: check-yaml
+        files: .*\.(yaml|yml)$
+  - repo: local
+    hooks:
+      - id: flake8
+        name: flake8
+        additional_dependencies:
+          - hacking>=2.0.0
+          - flake8-import-order>=0.13
+        language: python
+        entry: flake8
+        files: '^.*\.py$'
+        exclude: '^(doc|releasenotes|tools)/.*$'
diff --git a/doc/source/contributor/developing.rst b/doc/source/contributor/developing.rst
index 9142edb8..a70b3326 100644
--- a/doc/source/contributor/developing.rst
+++ b/doc/source/contributor/developing.rst
@@ -6,16 +6,18 @@ Communication
 -------------
 
 IRC Channel
-===========
+~~~~~~~~~~~
+
 The OpenStackClient team doesn't have regular meetings so if you have
 questions or anything you want to discuss, come to our channel:
 #openstack-sdks
 
+
 Testing
 -------
 
 Tox prerequisites and installation
-==================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Install the prerequisites for Tox:
 
@@ -23,23 +25,22 @@ Install the prerequisites for Tox:
 
   .. code-block:: bash
 
-    $ apt-get install gcc gettext python-dev libxml2-dev libxslt1-dev \
+    $ apt-get install gcc gettext python3-dev libxml2-dev libxslt1-dev \
       zlib1g-dev
 
   You may need to use pip install for some packages.
 
-
 * On RHEL or CentOS including Fedora:
 
   .. code-block:: bash
 
-    $ yum install gcc python-devel libxml2-devel libxslt-devel
+    $ yum install gcc python3-devel libxml2-devel libxslt-devel
 
 * On openSUSE or SUSE linux Enterprise:
 
   .. code-block:: bash
 
-    $ zypper install gcc python-devel libxml2-devel libxslt-devel
+    $ zypper install gcc python3-devel libxml2-devel libxslt-devel
 
 Install python-tox:
 
@@ -59,7 +60,7 @@ To run the full suite of tests maintained within OpenStackClient.
     virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild
     your virtualenv in a similar manner.
 
-To run tests for one or more specific test environments(for example, the most
+To run tests for one or more specific test environments (for example, the most
 common configuration of the latest Python version and PEP-8), list the
 environments with the ``-e`` option, separated by spaces:
 
@@ -70,7 +71,7 @@ environments with the ``-e`` option, separated by spaces:
 See ``tox.ini`` for the full list of available test environments.
 
 Running functional tests
-========================
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 OpenStackClient also maintains a set of functional tests that are optimally
 designed to be run against OpenStack's gate. Optionally, a developer may
@@ -90,7 +91,7 @@ To run a specific functional test:
     $ tox -e functional -- --regex functional.tests.compute.v2.test_server
 
 Running with PDB
-================
+~~~~~~~~~~~~~~~~
 
 Using PDB breakpoints with ``tox`` and ``testr`` normally does not work since
 the tests fail with a `BdbQuit` exception rather than stopping at the
@@ -109,8 +110,32 @@ For reference, the `debug`_ ``tox`` environment implements the instructions
 .. _`debug`: https://wiki.openstack.org/wiki/Testr#Debugging_.28pdb.29_Tests
 
 
-Building the Documentation
---------------------------
+Coding Style
+------------
+
+OpenStackClient uses `flake8`__ along with `hacking`__, an OpenStack-specific
+superset of ``flake8`` rules, to enforce coding style. This can be run manually
+using ``tox``:
+
+.. code-block:: bash
+
+    $ tox -e pep8
+
+Alternatively, you can use the `pre-commit framework`__ to allow running of
+some linters on each commit. This must be enabled locally to function:
+
+.. code-block:: bash
+
+    $ pip install --user pre-commit
+    $ pre-commit install --allow-missing-config
+
+.. __: https://flake8.pycqa.org/en/latest/
+.. __: https://docs.openstack.org/hacking/latest/user/hacking.html
+.. __: https://pre-commit.com/
+
+
+Documentation
+-------------
 
 The documentation is generated with Sphinx using the ``tox`` command. To
 create HTML docs, run the commands:
@@ -121,6 +146,7 @@ create HTML docs, run the commands:
 
 The resultant HTML will be in the ``doc/build/html`` directory.
 
+
 Release Notes
 -------------
 
@@ -156,6 +182,7 @@ To run the commands and see results:
 
 At last, look at the generated release notes files in ``releasenotes/build/html`` in your browser.
 
+
 Testing new code
 ----------------
 
@@ -174,7 +201,7 @@ or
    $ pip install -e .
 
 Standardize Import Format
-=========================
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 More information about Import Format, see `Import Order Guide
 <https://docs.openstack.org/hacking/latest/user/hacking.html#imports>`__.
@@ -193,7 +220,7 @@ The import order shows below:
    {{begin your code}}
 
 Example
-~~~~~~~
+^^^^^^^
 
 .. code-block:: python