Skip to content

Commit bf8aef5

Browse files
KonfektKonfekt
committed
add Vim help
1 parent 60ba5e1 commit bf8aef5

File tree

2 files changed

+357
-0
lines changed

2 files changed

+357
-0
lines changed

‎README.md

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# vim-python-pep8-indent
2+
3+
[![image](https://circleci.com/gh/Vimjas/vim-python-pep8-indent.svg?style=svg)](https://circleci.com/gh/Vimjas/vim-python-pep8-indent)
4+
5+
[![image](https://codecov.io/gh/Vimjas/vim-python-pep8-indent/branch/master/graph/badge.svg)](https://codecov.io/gh/Vimjas/vim-python-pep8-indent)
6+
7+
This small script modifies [Vim](http://www.vim.org/)'s indentation
8+
behavior to comply with [PEP8](http://www.python.org/dev/peps/pep-0008/)
9+
and my aesthetic preferences. Most importantly:
10+
11+
foobar(foo,
12+
bar)
13+
14+
and:
15+
16+
foobar(
17+
foo,
18+
bar
19+
)
20+
21+
## Installation
22+
23+
Install the plugin using your favorite plugin manager / method, a few
24+
examples follow:
25+
26+
### Pathogen
27+
28+
Follow the instructions on installing
29+
[Pathogen](https://github.com/tpope/vim-pathogen) and then:
30+
31+
``` shell-session
32+
$ cd ~/.vim/bundle
33+
$ git clone https://github.com/Vimjas/vim-python-pep8-indent.git
34+
```
35+
36+
### Vundle
37+
38+
Follow the instructions on installing
39+
[Vundle](https://github.com/gmarik/Vundle.vim) and add the appropriate
40+
plugin line into your `.vimrc`:
41+
42+
``` vim
43+
Plugin 'Vimjas/vim-python-pep8-indent'
44+
```
45+
46+
### NeoBundle
47+
48+
Follow the instructions on installing
49+
[NeoBundle](https://github.com/Shougo/neobundle.vim) and add the
50+
appropriate NeoBundle line into your `.vimrc`:
51+
52+
``` vim
53+
NeoBundle 'Vimjas/vim-python-pep8-indent'
54+
```
55+
56+
## Configuration
57+
58+
### g:python_pep8_indent_multiline_string
59+
60+
You can configure the initial indentation of multiline strings using
61+
`g:python_pep8_indent_multiline_string` (which can also be set per
62+
buffer). This defaults to `0`, which means that multiline strings are
63+
not indented. `-1` and positive values will be used as-is, where `-1` is
64+
a special value for Vim\'s `indentexpr`, and will keep the existing
65+
indent (using Vim\'s `autoindent` setting). `-2` is meant to be used for
66+
strings that are wrapped with `textwrap.dedent` etc. It will add a level
67+
of indentation if the multiline string started in the previous line,
68+
without any content in it already:
69+
70+
testdir.makeconftest("""
71+
_
72+
73+
With content already, it will be aligned to the opening parenthesis:
74+
75+
testdir.makeconftest("""def pytest_addoption(parser):
76+
_
77+
78+
Existing indentation (including `0`) in multiline strings will be kept,
79+
so this setting only applies to the indentation of new/empty lines.
80+
81+
### g:python_pep8_indent_hang_closing
82+
83+
Control closing bracket indentation with
84+
`python_pep8_indent_hang_closing`, set globally or per buffer.
85+
86+
By default (set to `0`), closing brackets line up with the opening line:
87+
88+
my_list = [
89+
1, 2, 3,
90+
4, 5, 6,
91+
]
92+
result = some_function_that_takes_arguments(
93+
'a', 'b', 'c',
94+
'd', 'e', 'f',
95+
)
96+
97+
With `python_pep8_indent_hang_closing = 1`, closing brackets line up
98+
with the items:
99+
100+
my_list = [
101+
1, 2, 3,
102+
4, 5, 6,
103+
]
104+
result = some_function_that_takes_arguments(
105+
'a', 'b', 'c',
106+
'd', 'e', 'f',
107+
)
108+
109+
## Troubleshooting
110+
111+
In case it is not working, please make sure your Vim is configured to
112+
load indent files (`filetype indent on`). This is typically the case
113+
when using a plugin manager, but check its docs.
114+
115+
Check `:verbose set indentexpr?` in a Python file, which should show
116+
something like the following:
117+
118+
> indentexpr=GetPythonPEPIndent(v:lnum)
119+
>
120+
> : Last set from
121+
> \~/.../plugged/vim-python-pep8-indent/indent/python.vim
122+
123+
## Notes
124+
125+
Please note that Kirill Klenov's
126+
[python-mode](https://github.com/klen/python-mode) ships its own version
127+
of this bundle. Therefore, if you want to use this version specifically,
128+
you'll have to disable python-mode's using:
129+
130+
``` vim
131+
let g:pymode_indent = 0
132+
```
133+
134+
## License and Authorship
135+
136+
This script is based on one from Vim's official [script
137+
repo](http://www.vim.org/scripts/script.php?script_id=974) that was
138+
*not* originally written by me. Unfortunately the indentation was off by
139+
one character in one case and the script hasn't been updated since 2005.
140+
141+
Even more unfortunately, I wasn't able to reach any of the original
142+
authors/maintainers: **David Bustos** and **Eric Mc Sween**.
143+
144+
So I fixed the annoyance with the help of [Steve
145+
Losh](http://stevelosh.com/) and am putting it out here so you don't
146+
have to patch the original yourself. The original patch is still
147+
available [here](https://gist.github.com/2965846).
148+
149+
Over the time a lot more improvements have been
150+
[contributed](https://github.com/hynek/vim-python-pep8-indent/blob/master/CONTRIBUTING.rst)
151+
by [generous
152+
people](https://github.com/hynek/vim-python-pep8-indent/graphs/contributors).
153+
154+
I'd like to thank the original authors here for their work and release
155+
it hereby to the *Public Domain* (using the
156+
[CC0](http://creativecommons.org/publicdomain/zero/1.0/) licence) since
157+
I hope that would be in their spirit. If anyone with a say in this
158+
objects, please let [me](https://hynek.me/) know immediately. Also, if
159+
someone is in contact with one of them, I would appreciate being
160+
introduced.
161+
162+
While my [Vimscript](http://learnvimscriptthehardway.stevelosh.com/)
163+
skills are still feeble, I intend to maintain it for now. This mainly
164+
means that I'll triage through bugs and pull requests but won't be
165+
fixing much myself.

‎doc/vim-python-pep8-indent.txt

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
vim-python-pep8-indent.txt
2+
3+
================================================================================
4+
CONTENTS *vim-python-pep8-indent-contents*
5+
6+
1. vim-python-pep8-indent..........|vim-python-pep8-indent-vim-python-pep8-indent|
7+
1.1. Installation........................|vim-python-pep8-indent-installation|
8+
1.1.1. Pathogen..........................|vim-python-pep8-indent-pathogen|
9+
1.1.2. Vundle..............................|vim-python-pep8-indent-vundle|
10+
1.1.3. NeoBundle........................|vim-python-pep8-indent-neobundle|
11+
1.2. Configuration......................|vim-python-pep8-indent-configuration|
12+
1.2.1. g:python_pep8_indent_multiline_string.|vim-python-pep8-indent-g:python_pep8_indent_multiline_string|
13+
1.2.2. g:python_pep8_indent_hang_closing.|vim-python-pep8-indent-g:python_pep8_indent_hang_closing|
14+
1.3. Troubleshooting..................|vim-python-pep8-indent-troubleshooting|
15+
1.4. Notes......................................|vim-python-pep8-indent-notes|
16+
1.5. License and Authorship....|vim-python-pep8-indent-license_and_authorship|
17+
18+
================================================================================
19+
VIM-PYTHON-PEP8-INDENT *vim-python-pep8-indent-vim-python-pep8-indent*
20+
21+
[](https://circleci.com/gh/Vimjas/vim-python-pep8-indent)
22+
23+
[](https://codecov.io/gh/Vimjas/vim-python-pep8-indent)
24+
25+
This small script modifies Vim (http://www.vim.org/)'s indentation
26+
behavior to comply with PEP8 (http://www.python.org/dev/peps/pep-0008/)
27+
and my aesthetic preferences. Most importantly:
28+
>
29+
foobar(foo,
30+
bar)
31+
<
32+
33+
and:
34+
>
35+
foobar(
36+
foo,
37+
bar
38+
)
39+
<
40+
41+
--------------------------------------------------------------------------------
42+
INSTALLATION *vim-python-pep8-indent-installation*
43+
44+
Install the plugin using your favorite plugin manager / method, a few
45+
examples follow:
46+
47+
PATHOGEN *vim-python-pep8-indent-pathogen*
48+
49+
Follow the instructions on installing
50+
Pathogen (https://github.com/tpope/vim-pathogen) and then:
51+
>
52+
$ cd ~/.vim/bundle
53+
$ git clone https://github.com/Vimjas/vim-python-pep8-indent.git
54+
<
55+
56+
VUNDLE *vim-python-pep8-indent-vundle*
57+
58+
Follow the instructions on installing
59+
Vundle (https://github.com/gmarik/Vundle.vim) and add the appropriate
60+
plugin line into your `.vimrc`:
61+
>
62+
Plugin 'Vimjas/vim-python-pep8-indent'
63+
<
64+
65+
NEOBUNDLE *vim-python-pep8-indent-neobundle*
66+
67+
Follow the instructions on installing
68+
NeoBundle (https://github.com/Shougo/neobundle.vim) and add the
69+
appropriate NeoBundle line into your `.vimrc`:
70+
>
71+
NeoBundle 'Vimjas/vim-python-pep8-indent'
72+
<
73+
74+
--------------------------------------------------------------------------------
75+
CONFIGURATION *vim-python-pep8-indent-configuration*
76+
77+
G:PYTHON_PEP8_INDENT_MULTILINE_STRING *vim-python-pep8-indent-g:python_pep8_indent_multiline_string*
78+
79+
You can configure the initial indentation of multiline strings using
80+
`g:python_pep8_indent_multiline_string` (which can also be set per
81+
buffer). This defaults to `0`, which means that multiline strings are
82+
not indented. `-1` and positive values will be used as-is, where `-1` is
83+
a special value for Vim\'s `indentexpr`, and will keep the existing
84+
indent (using Vim\'s `autoindent` setting). `-2` is meant to be used for
85+
strings that are wrapped with `textwrap.dedent` etc. It will add a level
86+
of indentation if the multiline string started in the previous line,
87+
without any content in it already:
88+
>
89+
testdir.makeconftest("""
90+
_
91+
<
92+
93+
With content already, it will be aligned to the opening parenthesis:
94+
>
95+
testdir.makeconftest("""def pytest_addoption(parser):
96+
_
97+
<
98+
99+
Existing indentation (including `0`) in multiline strings will be kept,
100+
so this setting only applies to the indentation of new/empty lines.
101+
102+
G:PYTHON_PEP8_INDENT_HANG_CLOSING *vim-python-pep8-indent-g:python_pep8_indent_hang_closing*
103+
104+
Control closing bracket indentation with
105+
`python_pep8_indent_hang_closing`, set globally or per buffer.
106+
107+
By default (set to `0`), closing brackets line up with the opening line:
108+
>
109+
my_list = [
110+
1, 2, 3,
111+
4, 5, 6,
112+
]
113+
result = some_function_that_takes_arguments(
114+
'a', 'b', 'c',
115+
'd', 'e', 'f',
116+
)
117+
<
118+
119+
With , closing brackets line up
120+
with the items:
121+
>
122+
my_list = [
123+
1, 2, 3,
124+
4, 5, 6,
125+
]
126+
result = some_function_that_takes_arguments(
127+
'a', 'b', 'c',
128+
'd', 'e', 'f',
129+
)
130+
<
131+
132+
--------------------------------------------------------------------------------
133+
TROUBLESHOOTING *vim-python-pep8-indent-troubleshooting*
134+
135+
In case it is not working, please make sure your Vim is configured to
136+
load indent files (). This is typically the case
137+
when using a plugin manager, but check its docs.
138+
139+
Check in a Python file, which should show
140+
something like the following:
141+
>
142+
indentexpr=GetPythonPEPIndent(v:lnum)
143+
: Last set from
144+
~/.../plugged/vim-python-pep8-indent/indent/python.vim
145+
<
146+
147+
--------------------------------------------------------------------------------
148+
NOTES *vim-python-pep8-indent-notes*
149+
150+
Please note that Kirill Klenov's
151+
python-mode (https://github.com/klen/python-mode) ships its own version
152+
of this bundle. Therefore, if you want to use this version specifically,
153+
you'll have to disable python-mode's using:
154+
>
155+
let g:pymode_indent = 0
156+
<
157+
158+
--------------------------------------------------------------------------------
159+
LICENSE AND AUTHORSHIP *vim-python-pep8-indent-license_and_authorship*
160+
161+
This script is based on one from Vim's official script
162+
repo (http://www.vim.org/scripts/script.php?script_id=974) that was
163+
not originally written by me. Unfortunately the indentation was off by
164+
one character in one case and the script hasn't been updated since 2005.
165+
166+
Even more unfortunately, I wasn't able to reach any of the original
167+
authors/maintainers: David Bustos and Eric Mc Sween.
168+
169+
So I fixed the annoyance with the help of Steve
170+
Losh (http://stevelosh.com/) and am putting it out here so you don't
171+
have to patch the original yourself. The original patch is still
172+
available here (https://gist.github.com/2965846).
173+
174+
Over the time a lot more improvements have been
175+
contributed (https://github.com/hynek/vim-python-pep8-indent/blob/master/CONTRIBUTING.rst)
176+
by generous
177+
people (https://github.com/hynek/vim-python-pep8-indent/graphs/contributors).
178+
179+
I'd like to thank the original authors here for their work and release
180+
it hereby to the Public Domain (using the
181+
CC0 (http://creativecommons.org/publicdomain/zero/1.0/) licence) since
182+
I hope that would be in their spirit. If anyone with a say in this
183+
objects, please let me (https://hynek.me/) know immediately. Also, if
184+
someone is in contact with one of them, I would appreciate being
185+
introduced.
186+
187+
While my Vimscript (http://learnvimscriptthehardway.stevelosh.com/)
188+
skills are still feeble, I intend to maintain it for now. This mainly
189+
means that I'll triage through bugs and pull requests but won't be
190+
fixing much myself.
191+
192+
vim:tw=78:ts=8:ft=help:norl:

0 commit comments

Comments
 (0)