From e380665530609bb2705eff01143de8ed09202caa Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sun, 13 Nov 2016 14:32:23 -0600 Subject: [PATCH] Add a man page for Flake8 Document Flake8 for users expecting `man flake8` to work and include the man page in Flake8's documentation. Closes #247 --- docs/source/conf.py | 2 +- docs/source/index.rst | 1 + docs/source/manpage.rst | 150 ++++++++++++++++++++++++++++++++++++++++ tox.ini | 1 + 4 files changed, 153 insertions(+), 1 deletion(-) create mode 100644 docs/source/manpage.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index c7a0fd0..0c0b8de 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -264,7 +264,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'flake8', u'flake8 Documentation', + ('manpage', 'flake8', u'Flake8 Command Line Documentation', [author], 1) ] diff --git a/docs/source/index.rst b/docs/source/index.rst index 51b0189..9488985 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -89,6 +89,7 @@ and how to specify them on the command-line or in configuration files. :maxdepth: 2 user/index + Flake8 man page Plugin Developer Guide ====================== diff --git a/docs/source/manpage.rst b/docs/source/manpage.rst new file mode 100644 index 0000000..4988de4 --- /dev/null +++ b/docs/source/manpage.rst @@ -0,0 +1,150 @@ +======== + flake8 +======== + +SYNOPSIS +======== + +.. code:: + + flake8 [options] [ ...] + + flake8 --help + +DESCRIPTION +=========== + +``flake8`` is a command-line utility for enforcing style consistency across +Python projects. By default it includes lint checks provided by the PyFlakes +project, PEP-0008 inspired style checks provided by the PyCodeStyle project, +and McCabe complexity checking provided by the McCabe project. It will also +run third-party extensions if they are found and installed. + +OPTIONS +======= + +It is important to note that third-party extensions may add options which are +not represented here. To see all options available in your installation, run:: + + flake8 --help + +All options available as of Flake8 3.1.0:: + + --version show program's version number and exit + -h, --help show this help message and exit + -v, --verbose Print more information about what is happening in + flake8. This option is repeatable and will increase + verbosity each time it is repeated. + -q, --quiet Report only file names, or nothing. This option is + repeatable. + --count Print total number of errors and warnings to standard + error and set the exit code to 1 if total is not + empty. + --diff Report changes only within line number ranges in the + unified diff provided on standard in by the user. + --exclude=patterns Comma-separated list of files or directories to + exclude. (Default: + .svn,CVS,.bzr,.hg,.git,__pycache__,.tox,.eggs,*.egg) + --filename=patterns Only check for filenames matching the patterns in this + comma-separated list. (Default: *.py) + --stdin-display-name=STDIN_DISPLAY_NAME + The name used when reporting errors from code passed + via stdin. This is useful for editors piping the file + contents to flake8. (Default: stdin) + --format=format Format errors according to the chosen formatter. + --hang-closing Hang closing bracket instead of matching indentation + of opening bracket's line. + --ignore=errors Comma-separated list of errors and warnings to ignore + (or skip). For example, ``--ignore=E4,E51,W234``. + (Default: E121,E123,E126,E226,E24,E704,W503,W504) + --max-line-length=n Maximum allowed line length for the entirety of this + run. (Default: 79) + --select=errors Comma-separated list of errors and warnings to enable. + For example, ``--select=E4,E51,W234``. (Default: + E,F,W,C90) + --disable-noqa Disable the effect of "# noqa". This will report + errors on lines with "# noqa" at the end. + --show-source Show the source generate each error or warning. + --statistics Count errors and warnings. + --enable-extensions=ENABLE_EXTENSIONS + Enable plugins and extensions that are otherwise + disabled by default + --exit-zero Exit with status code "0" even if there are errors. + --install-hook=INSTALL_HOOK + Install a hook that is run prior to a commit for the + supported version control systema. + -j JOBS, --jobs=JOBS Number of subprocesses to use to run checks in + parallel. This is ignored on Windows. The default, + "auto", will auto-detect the number of processors + available to use. (Default: auto) + --output-file=OUTPUT_FILE + Redirect report to a file. + --tee Write to stdout and output-file. + --append-config=APPEND_CONFIG + Provide extra config files to parse in addition to the + files found by Flake8 by default. These files are the + last ones read and so they take the highest precedence + when multiple files provide the same option. + --config=CONFIG Path to the config file that will be the authoritative + config source. This will cause Flake8 to ignore all + other configuration files. + --isolated Ignore all found configuration files. + --benchmark Print benchmark information about this run of Flake8 + --bug-report Print information necessary when preparing a bug + report + --builtins=BUILTINS define more built-ins, comma separated + --doctests check syntax of the doctests + --include-in-doctest=INCLUDE_IN_DOCTEST + Run doctests only on these files + --exclude-from-doctest=EXCLUDE_FROM_DOCTEST + Skip these files when running doctests + --max-complexity=MAX_COMPLEXITY + McCabe complexity threshold + +EXAMPLES +======== + +Simply running flake8 against the current directory:: + + flake8 + flake8 . + +Running flake8 against a specific path:: + + flake8 path/to/file.py + +Ignoring violations from flake8:: + + flake8 --ignore E101 + flake8 --ignore E1,E202 + +Only report certain violations:: + + flake8 --select E101 + flake8 --select E2,E742 + +Analyzing only a diff:: + + git diff -U0 | flake8 --diff - + +Generate information for a bug report:: + + flake8 --bug-report + +SEE ALSO +======== + +Flake8 documentation: http://flake8.pycqa.org + +Flake8 Options and Examples: http://flake8.pycqa.org/en/latest/user/options.html + +PyCodeStyle documentation: http://pycodestyle.pycqa.org + +PyFlakes: https://github.com/pycqa/pyflakes + +McCabe: https://github.com/pycqa/mccabe + +BUGS +==== + +Please report all bugs to https://gitlab.com/pycqa/flake8 diff --git a/tox.ini b/tox.ini index d1f515b..2e4504f 100644 --- a/tox.ini +++ b/tox.ini @@ -97,6 +97,7 @@ deps = -rdocs/source/requirements.txt commands = sphinx-build -E -W -c docs/source/ -b html docs/source/ docs/build/html + sphinx-build -E -W -c docs/source/ -b man docs/source/ docs/build/man [testenv:serve-docs] basepython = python3