add Vim help

README.md

@@ -0,0 +1,165 @@
+# vim-python-pep8-indent
+
+[![image](https://circleci.com/gh/Vimjas/vim-python-pep8-indent.svg?style=svg)](https://circleci.com/gh/Vimjas/vim-python-pep8-indent)
+
+[![image](https://codecov.io/gh/Vimjas/vim-python-pep8-indent/branch/master/graph/badge.svg)](https://codecov.io/gh/Vimjas/vim-python-pep8-indent)
+
+This small script modifies [Vim](http://www.vim.org/)'s indentation
+behavior to comply with [PEP8](http://www.python.org/dev/peps/pep-0008/)
+and my aesthetic preferences. Most importantly:
+
+    foobar(foo,
+           bar)
+
+and:
+
+    foobar(
+       foo,
+       bar
+    )
+
+## Installation
+
+Install the plugin using your favorite plugin manager / method, a few
+examples follow:
+
+### Pathogen
+
+Follow the instructions on installing
+[Pathogen](https://github.com/tpope/vim-pathogen) and then:
+
+``` shell-session
+$ cd ~/.vim/bundle
+$ git clone https://github.com/Vimjas/vim-python-pep8-indent.git
+```
+
+### Vundle
+
+Follow the instructions on installing
+[Vundle](https://github.com/gmarik/Vundle.vim) and add the appropriate
+plugin line into your `.vimrc`:
+
+``` vim
+Plugin 'Vimjas/vim-python-pep8-indent'
+```
+
+### NeoBundle
+
+Follow the instructions on installing
+[NeoBundle](https://github.com/Shougo/neobundle.vim) and add the
+appropriate NeoBundle line into your `.vimrc`:
+
+``` vim
+NeoBundle 'Vimjas/vim-python-pep8-indent'
+```
+
+## Configuration
+
+### g:python_pep8_indent_multiline_string
+
+You can configure the initial indentation of multiline strings using
+`g:python_pep8_indent_multiline_string` (which can also be set per
+buffer). This defaults to `0`, which means that multiline strings are
+not indented. `-1` and positive values will be used as-is, where `-1` is
+a special value for Vim\'s `indentexpr`, and will keep the existing
+indent (using Vim\'s `autoindent` setting). `-2` is meant to be used for
+strings that are wrapped with `textwrap.dedent` etc. It will add a level
+of indentation if the multiline string started in the previous line,
+without any content in it already:
+
+    testdir.makeconftest("""
+        _
+
+With content already, it will be aligned to the opening parenthesis:
+
+    testdir.makeconftest("""def pytest_addoption(parser):
+                         _
+
+Existing indentation (including `0`) in multiline strings will be kept,
+so this setting only applies to the indentation of new/empty lines.
+
+### g:python_pep8_indent_hang_closing
+
+Control closing bracket indentation with
+`python_pep8_indent_hang_closing`, set globally or per buffer.
+
+By default (set to `0`), closing brackets line up with the opening line:
+
+    my_list = [
+        1, 2, 3,
+        4, 5, 6,
+    ]
+    result = some_function_that_takes_arguments(
+        'a', 'b', 'c',
+        'd', 'e', 'f',
+    )
+
+With `python_pep8_indent_hang_closing = 1`, closing brackets line up
+with the items:
+
+    my_list = [
+        1, 2, 3,
+        4, 5, 6,
+        ]
+    result = some_function_that_takes_arguments(
+        'a', 'b', 'c',
+        'd', 'e', 'f',
+        )
+
+## Troubleshooting
+
+In case it is not working, please make sure your Vim is configured to
+load indent files (`filetype indent on`). This is typically the case
+when using a plugin manager, but check its docs.
+
+Check `:verbose set indentexpr?` in a Python file, which should show
+something like the following:
+
+> indentexpr=GetPythonPEPIndent(v:lnum)
+>
+> :   Last set from
+>     \~/.../plugged/vim-python-pep8-indent/indent/python.vim
+
+## Notes
+
+Please note that Kirill Klenov's
+[python-mode](https://github.com/klen/python-mode) ships its own version
+of this bundle. Therefore, if you want to use this version specifically,
+you'll have to disable python-mode's using:
+
+``` vim
+let g:pymode_indent = 0
+```
+
+## License and Authorship
+
+This script is based on one from Vim's official [script
+repo](http://www.vim.org/scripts/script.php?script_id=974) that was
+*not* originally written by me. Unfortunately the indentation was off by
+one character in one case and the script hasn't been updated since 2005.
+
+Even more unfortunately, I wasn't able to reach any of the original
+authors/maintainers: **David Bustos** and **Eric Mc Sween**.
+
+So I fixed the annoyance with the help of [Steve
+Losh](http://stevelosh.com/) and am putting it out here so you don't
+have to patch the original yourself. The original patch is still
+available [here](https://gist.github.com/2965846).
+
+Over the time a lot more improvements have been
+[contributed](https://github.com/hynek/vim-python-pep8-indent/blob/master/CONTRIBUTING.rst)
+by [generous
+people](https://github.com/hynek/vim-python-pep8-indent/graphs/contributors).
+
+I'd like to thank the original authors here for their work and release
+it hereby to the *Public Domain* (using the
+[CC0](http://creativecommons.org/publicdomain/zero/1.0/) licence) since
+I hope that would be in their spirit. If anyone with a say in this
+objects, please let [me](https://hynek.me/) know immediately. Also, if
+someone is in contact with one of them, I would appreciate being
+introduced.
+
+While my [Vimscript](http://learnvimscriptthehardway.stevelosh.com/)
+skills are still feeble, I intend to maintain it for now. This mainly
+means that I'll triage through bugs and pull requests but won't be
+fixing much myself.

doc/vim-python-pep8-indent.txt

@@ -0,0 +1,192 @@
+vim-python-pep8-indent.txt
+
+================================================================================
+CONTENTS                                         *python-pep8-indent-contents*
+
+1. vim-python-pep8-indent..........|python-pep8-indent-vim-python-pep8-indent|
+    1.1. Installation........................|python-pep8-indent-installation|
+        1.1.1. Pathogen..........................|python-pep8-indent-pathogen|
+        1.1.2. Vundle..............................|python-pep8-indent-vundle|
+        1.1.3. NeoBundle........................|python-pep8-indent-neobundle|
+    1.2. Configuration......................|python-pep8-indent-configuration|
+        1.2.1. g:python_pep8_indent_multiline_string.|python-pep8-indent-g:python_pep8_indent_multiline_string|
+        1.2.2. g:python_pep8_indent_hang_closing.|python-pep8-indent-g:python_pep8_indent_hang_closing|
+    1.3. Troubleshooting..................|python-pep8-indent-troubleshooting|
+    1.4. Notes......................................|python-pep8-indent-notes|
+    1.5. License and Authorship....|python-pep8-indent-license_and_authorship|
+
+================================================================================
+VIM-PYTHON-PEP8-INDENT             *python-pep8-indent-vim-python-pep8-indent*
+
+[](https://circleci.com/gh/Vimjas/vim-python-pep8-indent)
+
+[](https://codecov.io/gh/Vimjas/vim-python-pep8-indent)
+
+This small script modifies Vim (http://www.vim.org/)'s indentation
+behavior to comply with PEP8 (http://www.python.org/dev/peps/pep-0008/)
+and my aesthetic preferences. Most importantly:
+>
+    foobar(foo,
+           bar)
+<
+
+and:
+>
+    foobar(
+       foo,
+       bar
+    )
+<
+
+--------------------------------------------------------------------------------
+INSTALLATION                                 *python-pep8-indent-installation*
+
+Install the plugin using your favorite plugin manager / method, a few
+examples follow:
+
+PATHOGEN                                         *python-pep8-indent-pathogen*
+
+Follow the instructions on installing
+Pathogen (https://github.com/tpope/vim-pathogen) and then:
+>
+    $ cd ~/.vim/bundle
+    $ git clone https://github.com/Vimjas/vim-python-pep8-indent.git
+<
+
+VUNDLE                                             *python-pep8-indent-vundle*
+
+Follow the instructions on installing
+Vundle (https://github.com/gmarik/Vundle.vim) and add the appropriate
+plugin line into your `.vimrc`:
+>
+    Plugin 'Vimjas/vim-python-pep8-indent'
+<
+
+NEOBUNDLE                                       *python-pep8-indent-neobundle*
+
+Follow the instructions on installing
+NeoBundle (https://github.com/Shougo/neobundle.vim) and add the
+appropriate NeoBundle line into your `.vimrc`:
+>
+    NeoBundle 'Vimjas/vim-python-pep8-indent'
+<
+
+--------------------------------------------------------------------------------
+CONFIGURATION                               *python-pep8-indent-configuration*
+
+G:PYTHON_PEP8_INDENT_MULTILINE_STRING *python-pep8-indent-g:python_pep8_indent_multiline_string*
+
+You can configure the initial indentation of multiline strings using
+`g:python_pep8_indent_multiline_string` (which can also be set per
+buffer). This defaults to `0`, which means that multiline strings are
+not indented. `-1` and positive values will be used as-is, where `-1` is
+a special value for Vim\'s `indentexpr`, and will keep the existing
+indent (using Vim\'s `autoindent` setting). `-2` is meant to be used for
+strings that are wrapped with `textwrap.dedent` etc. It will add a level
+of indentation if the multiline string started in the previous line,
+without any content in it already:
+>
+    testdir.makeconftest("""
+        _
+<
+
+With content already, it will be aligned to the opening parenthesis:
+>
+    testdir.makeconftest("""def pytest_addoption(parser):
+                         _
+<
+
+Existing indentation (including `0`) in multiline strings will be kept,
+so this setting only applies to the indentation of new/empty lines.
+
+G:PYTHON_PEP8_INDENT_HANG_CLOSING *python-pep8-indent-g:python_pep8_indent_hang_closing*
+
+Control closing bracket indentation with
+`python_pep8_indent_hang_closing`, set globally or per buffer.
+
+By default (set to `0`), closing brackets line up with the opening line:
+>
+    my_list = [
+        1, 2, 3,
+        4, 5, 6,
+    ]
+    result = some_function_that_takes_arguments(
+        'a', 'b', 'c',
+        'd', 'e', 'f',
+    )
+<
+
+With , closing brackets line up
+with the items:
+>
+    my_list = [
+        1, 2, 3,
+        4, 5, 6,
+        ]
+    result = some_function_that_takes_arguments(
+        'a', 'b', 'c',
+        'd', 'e', 'f',
+        )
+<
+
+--------------------------------------------------------------------------------
+TROUBLESHOOTING                           *python-pep8-indent-troubleshooting*
+
+In case it is not working, please make sure your Vim is configured to
+load indent files (). This is typically the case
+when using a plugin manager, but check its docs.
+
+Check  in a Python file, which should show
+something like the following:
+>
+    indentexpr=GetPythonPEPIndent(v:lnum)
+    :   Last set from
+        ~/.../plugged/vim-python-pep8-indent/indent/python.vim
+<
+
+--------------------------------------------------------------------------------
+NOTES                                               *python-pep8-indent-notes*
+
+Please note that Kirill Klenov's
+python-mode (https://github.com/klen/python-mode) ships its own version
+of this bundle. Therefore, if you want to use this version specifically,
+you'll have to disable python-mode's using:
+>
+    let g:pymode_indent = 0
+<
+
+--------------------------------------------------------------------------------
+LICENSE AND AUTHORSHIP             *python-pep8-indent-license_and_authorship*
+
+This script is based on one from Vim's official script
+repo (http://www.vim.org/scripts/script.php?script_id=974) that was
+not originally written by me. Unfortunately the indentation was off by
+one character in one case and the script hasn't been updated since 2005.
+
+Even more unfortunately, I wasn't able to reach any of the original
+authors/maintainers: David Bustos and Eric Mc Sween.
+
+So I fixed the annoyance with the help of Steve
+Losh (http://stevelosh.com/) and am putting it out here so you don't
+have to patch the original yourself. The original patch is still
+available here (https://gist.github.com/2965846).
+
+Over the time a lot more improvements have been
+contributed (https://github.com/hynek/vim-python-pep8-indent/blob/master/CONTRIBUTING.rst)
+by generous
+people (https://github.com/hynek/vim-python-pep8-indent/graphs/contributors).
+
+I'd like to thank the original authors here for their work and release
+it hereby to the Public Domain (using the
+CC0 (http://creativecommons.org/publicdomain/zero/1.0/) licence) since
+I hope that would be in their spirit. If anyone with a say in this
+objects, please let me (https://hynek.me/) know immediately. Also, if
+someone is in contact with one of them, I would appreciate being
+introduced.
+
+While my Vimscript (http://learnvimscriptthehardway.stevelosh.com/)
+skills are still feeble, I intend to maintain it for now. This mainly
+means that I'll triage through bugs and pull requests but won't be
+fixing much myself.
+
+ vim:tw=78:ts=8:ft=help:norl: