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