Metadata-Version: 1.1
Name: plone.recipe.codeanalysis
Version: 1.0b1
Summary: UNKNOWN
Home-page: http://github.com/plone/plone.recipe.codeanalysis/
Author: Timo Stollenwerk
Author-email: contact@timostollenwerk.net
License: gpl
Description: .. contents::
        
        .. image:: https://travis-ci.org/plone/plone.recipe.codeanalysis.png?branch=master
            :target: http://travis-ci.org/plone/plone.recipe.codeanalysis
        
        Introduction
        ============
        
        plone.recipe.codeanalysis provides static code analysis for buildout-based
        Python projects, including flake8, jshint, csslint, zptlint, and other code
        checks.
        
        This buildout recipe creates a script to run the code analysis::
        
            bin/code-analysis
        
        By default plone.recipe.codeanalysis also creates a git pre-commit hook, in
        order to run the code analysis automatically before each commit.
        
        Code repository:
        
            https://github.com/plone/plone.recipe.codeanalysis
        
        Continuous Integration:
        
            https://travis-ci.org/plone/plone.recipe.codeanalysis
        
        Issue Tracker:
        
            https://github.com/plone/plone.recipe.codeanalysis/issues
        
        
        Supported options
        =================
        
        The recipe supports the following options:
        
        **directory**
            Directory that is subject to the code analysis. This option is required.
        
        **pre-commit-hook**
            If set to True, a git pre-commit hook is installed that runs the code
            analysis before each commit.
        
        **flake8**
            If set to True, run Flake8 code analysis. Default is True.
        
        **flake8-ignore**
            Skip errors or warnings. See `Flake8 documentation`_ for error codes.
            Default is None.
        
        **flake8-exclude**
            Comma-separated filename and glob patterns default. Say you want to
            exclude bootstrap.py, setup.py and all collective.* and plone.* packages.
            Just set "flake8-exclude=bootstrap.py,docs,*.egg,setup.py,collective.*,
            plone.*" in your buildout configuration. Default is
            'bootstrap.py,docs,*.egg'.
        
        **flake8-max-complexity**
            McCabe complexity threshold. Default is 10.
        
        **flake8-max-line-length**
            Set maximum allowed line length. Default is 79.
        
        **jshint**
            If set to True, jshint code analysis is run. Default is False. Please note
            that plone.recipe.codeanalysis requires jshint >= 1.0.
        
        **jshint-bin**
            JSHint executable. Default is 'jshint'. If you have JSHint installed on
            your system and in your path, there is nothing to do. To install JSHint in
            your buildout, use the following::
        
                [jshint]
                recipe = gp.recipe.node
                npms = jshint
                scripts = jshint
        
            set jshint-bin to '${buildout:directory}/bin/jshint'.
        
        **jshint-exclude**
            Allows you to specify directories which you don't want to be linted.
            Default is none. If you want JSHint to skip some files you can list them
            in a file named ``.jshintignore``. See `JSHint documentation`_ for more
            details.
        
        **csslint**
            If set to True, CSSLint code analysis is run. Default is False.
        
        **csslint-bin**
            CSS Lint executable. Default is 'csslint'. If you have CSS Lint installed
            on your system and in your path, there is nothing to do. To install CSS
            Lint in your buildout, use the following::
        
                [csslint]
                recipe = gp.recipe.node
                npms = csslint
                scripts = csslint
        
            set csslint-bin to '${buildout:directory}/bin/csslint'.
        
        **csslint-quiet**
            Normally, CSS Lint outputs information about every file that is checked
            regardless of problems. This option instructs CSS Lint to only output
            information to the console when errors are present. Otherwise, nothing is
            output. Default is ``True``.
        
        **csslint-ignore**
            This option allows you to specify which CSS Lint rules to turn off. The
            rules are represented as a comma-delimited list of rule IDs. By default,
            the following rules will be ignored as they are `considered useless`_::
        
            * adjoining-classes
            * floats
            * font-faces
            * font-sizes
            * ids
            * qualified-headings
            * unique-headings
        
            For a detailed list and description of the rules see
            `CSS Lint documentation`_.
        
        **csslint-exclude-list**
            This option specifies the files and directories CSS Lint will ignore.
            Default is no exclude list.
        
            You can specify more than one file or directory using a comma, such as::
        
                csslint-exclude-list = style.css,extras/
        
        .. Note::
            You should use the full path of the file or directory you want to exclude.
        
        **zptlint**
            If set to True, zptlint code analysis is run. Default is False.
        
            Note that the buildout itself already depends on zptlint, so no extra
            configuration is needed.
        
        **zptlint-bin**
            Set the path to a custom version of zptlint. Default is ``bin/zptlint``.
        
        **deprecated-methods**
            If set to True, warnings about deprecated methods will be printed. Default
            is False.
        
        **utf8-header**
            If set to True, Python files without a utf-8 header (like
            ``# -*- coding: utf-8 -*-``) will cause a warning. Default is False.
        
        **clean-lines**
            If set to True, **any file** containing trailing spaces or tabs anywhere
            on the lines will cause a warning. Default is False.
        
        **prefer-single-quotes**
            If set to True, Python files will be scanned searching for strings quoted
            with double quote signs (``"``). Default is False.
        
        **string-formatting**
            If set to True, Python files will be scanned searching for old-style
            string formatting (i.e. ``'%s' % var``). See `PEP 3101`_. Default is
            False.
        
        **imports**
            If set to True, checks that imports in Python files follow `plone.api
            conventions`_. Default is False.
        
        **debug-statements**
            If set to True, scan Python files looking for debug-like statements.
            Default is False.
        
        .. _`considered useless`: http://2002-2012.mattwilcox.net/archive/entry/id/1054/
        .. _`CSS Lint documentation`: https://github.com/stubbornella/csslint/wiki/Rules
        .. _`JSHint documentation`: http://jshint.com/docs/
        .. _`Flake8 documentation`: http://flake8.readthedocs.org/en/latest/warnings.html#error-codes
        .. _`PEP 3101`: http://www.python.org/dev/peps/pep-3101/
        .. _`plone.api conventions`: http://ploneapi.readthedocs.org/en/latest/contribute/conventions.html#about-imports
        
        Detailed Documentation
        **********************
        
        Example usage
        =============
        
        Minimal buildout::
        
            >>> write('buildout.cfg',
            ... """
            ... [buildout]
            ... parts = code-analysis
            ...
            ... [code-analysis]
            ... recipe = plone.recipe.codeanalysis
            ... directory = %(directory)s
            ... """ % {
            ...     'directory' : '${buildout:directory}/plone/recipe/codeanalysis',
            ... })
        
        Running the buildout gives us a 'code-analysis' script that runs the entire
        code analysis::
        
            >>> buildout_output_lower = system(buildout).lower()
            >>> '/sample-buildout/bin/code-analysis' in buildout_output_lower
            True
        
        It is also possible to run single code analysis scripts::
        
            >>> '/sample-buildout/bin/code-analysis-flake8' in buildout_output_lower
            True
            >>> '/sample-buildout/bin/code-analysis-jshint' in buildout_output_lower
            True
        
        Flake 8 and ZPTLint are installed by the buildout script, there is no need to
        install them on the system::
        
            >>> '/sample-buildout/bin/flake8' in buildout_output_lower
            True
        
            >>> '/sample-buildout/bin/zptlint' in buildout_output_lower
            True
        
        
        Deprecate method analysis script is installed::
        
            >>> '/sample-buildout/bin/code-analysis-deprecated-methods' in buildout_output_lower
            True
        
        The script to check if python files have an utf-8 encoding header is installed::
        
            >>> '/sample-buildout/bin/code-analysis-utf8-header' in buildout_output_lower
            True
        
        The script to warn about trailing spaces or tabs on files is installed::
        
            >>> '/sample-buildout/bin/code-analysis-clean-lines' in buildout_output_lower
            True
        
        Double quotes checker script is installed::
        
            >>> '/sample-buildout/bin/code-analysis-prefer-single-quotes' in buildout_output_lower
            True
        
        The script to check for old style string formatting is installed::
        
            >>> '/sample-buildout/bin/code-analysis-string-formatting' in buildout_output_lower
            True
        
        The script to check for plone.api style imports is installed::
        
            >>> '/sample-buildout/bin/code-analysis-imports' in buildout_output_lower
            True
        
        The script to check for debug-like statements in python code is installed::
        
            >>> '/sample-buildout/bin/code-analysis-debug-statements' in buildout_output_lower
            True
        
        By default a git pre-commit hook is installed. Though, this does not work if
        the current directory is not a git repository::
        
            >>> 'unable to create git pre-commit hook, this does not seem to be a git repository' in buildout_output_lower
            True
        
        If we have a git repository::
        
            >>> import subprocess
            >>> subprocess.call(['mkdir', '-p', '.git/hooks'])
            0
        
        And run buildout again::
        
            >>> buildout_output_lower = system(buildout).lower()
        
        Then the git pre-commit hook has been installed::
        
            >>> 'install git pre-commit hook.' in buildout_output_lower
            True
        
        Contributors
        ************
        
        - Timo Stollenwerk, Original Author
        - Gil Forcada
        - Héctor Velarde
        
        Change history
        **************
        
        1.0b1 (2013-08-12)
        ------------------
        
        - Workaround over JSHint limitations to avoid displaying warning messages as
          errors (closes #13).
          [hvelarde]
        
        - Fix CSS Lint validation and implement new 'csslint-quiet' option.
          [hvelarde]
        
        - Fix package distribution.
          [hvelarde]
        
        
        1.0a1 (2013-08-04)
        ------------------
        
        - Initial release.
          [timo]
        
        Download
        ********
        
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
