]> git.madduck.net Git - etc/vim.git/blob - .vim/bundle/vim-python-pep8-indent/README.rst

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

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