README.rst

   1 vim-python-pep8-indent
   2 ======================
   3
   4 .. image:: https://travis-ci.org/Vimjas/vim-python-pep8-indent.png?branch=master
   5    :target: https://travis-ci.org/Vimjas/vim-python-pep8-indent
   6
   7 This small script modifies Vim_’s indentation behavior to comply with PEP8_ and my aesthetic preferences.
   8 Most importantly::
   9
  10    foobar(foo,
  11           bar)
  12
  13 and::
  14
  15    foobar(
  16       foo,
  17       bar
  18    )
  19
  20
  21 Installation
  22 ------------
  23
  24
  25 Pathogen
  26 ^^^^^^^^
  27
  28 Follow the instructions on installing Pathogen_ and then:
  29
  30 .. code-block:: shell-session
  31
  32    $ cd ~/.vim/bundle
  33    $ git clone https://github.com/Vimjas/vim-python-pep8-indent.git
  34
  35
  36 Vundle
  37 ^^^^^^
  38
  39 Follow the instructions on installing Vundle_ and add the appropriate plugin line into your ``.vimrc``:
  40
  41 .. code-block:: vim
  42
  43    Plugin 'Vimjas/vim-python-pep8-indent'
  44
  45
  46 NeoBundle
  47 ^^^^^^^^^
  48
  49 Follow the instructions on installing NeoBundle_ and add the appropriate NeoBundle line into your ``.vimrc``:
  50
  51 .. code-block:: vim
  52
  53    NeoBundle 'Vimjas/vim-python-pep8-indent'
  54
  55
  56 Configuration
  57 -------------
  58
  59 g:python_pep8_indent_multiline_string
  60 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  61
  62 You can configure the initial indentation of multiline strings using ``g:python_pep8_indent_multiline_string`` (which can also be set per buffer).
  63 This defaults to ``0``, which means that multiline strings are not indented.
  64 ``-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).
  65 ``-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::
  66
  67    testdir.makeconftest("""
  68        _
  69
  70 With content already, it will be aligned to the opening parenthesis::
  71
  72    testdir.makeconftest("""def pytest_addoption(parser):
  73                         _
  74
  75 Existing indentation (including ``0``) in multiline strings will be kept, so this setting only applies to the indentation of new/empty lines.
  76
  77 g:python_pep8_indent_hang_closing
  78 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  79
  80 Control closing bracket indentation with ``python_pep8_indent_hang_closing``, set globally or per buffer.
  81
  82 By default (set to ``0``), closing brackets line up with the opening line::
  83
  84    my_list = [
  85        1, 2, 3,
  86        4, 5, 6,
  87    ]
  88    result = some_function_that_takes_arguments(
  89        'a', 'b', 'c',
  90        'd', 'e', 'f',
  91    )
  92
  93 With ``python_pep8_indent_hang_closing = 1``, closing brackets line up with the items::
  94
  95    my_list = [
  96        1, 2, 3,
  97        4, 5, 6,
  98        ]
  99    result = some_function_that_takes_arguments(
 100        'a', 'b', 'c',
 101        'd', 'e', 'f',
 102        )
 103
 104 Notes
 105 -----
 106
 107 Please note that Kirill Klenov’s python-mode_ ships its own version of this bundle.
 108 Therefore, if you want to use this version specifically, you’ll have to disable python-mode’s using:
 109
 110 .. code-block:: vim
 111
 112    let g:pymode_indent = 0
 113
 114
 115 License and Authorship
 116 ----------------------
 117
 118 This script is based on one from Vim’s official `script repo`_  that was *not* originally written by me.
 119 Unfortunately the indentation was off by one character in one case and the script hasn’t been updated since 2005.
 120
 121 Even more unfortunately, I wasn’t able to reach any of the original authors/maintainers:
 122 **David Bustos** and **Eric Mc Sween**.
 123
 124 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.
 125 The original patch is still available here_.
 126
 127 Over the time a lot more improvements have been contributed_ by `generous people`_.
 128
 129 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.
 130 If anyone with a say in this objects, please let me_ know immediately.
 131 Also, if someone is in contact with one of them, I would appreciate being introduced.
 132
 133 While my Vimscript_ skills are still feeble, I intend to maintain it for now.
 134 This mainly means that I’ll triage through bugs and pull requests but won’t be fixing much myself.
 135
 136
 137 .. _Vim: http://www.vim.org/
 138 .. _PEP8: http://www.python.org/dev/peps/pep-0008/
 139 .. _`script repo`: http://www.vim.org/scripts/script.php?script_id=974
 140 .. _`Steve Losh`: http://stevelosh.com/
 141 .. _here: https://gist.github.com/2965846
 142 .. _Neobundle: https://github.com/Shougo/neobundle.vim
 143 .. _Pathogen: https://github.com/tpope/vim-pathogen
 144 .. _python-mode: https://github.com/klen/python-mode
 145 .. _`Vimscript`: http://learnvimscriptthehardway.stevelosh.com/
 146 .. _vundle: https://github.com/gmarik/Vundle.vim
 147 .. _me: https://hynek.me/
 148 .. _CC0: http://creativecommons.org/publicdomain/zero/1.0/
 149 .. _contributed: https://github.com/hynek/vim-python-pep8-indent/blob/master/CONTRIBUTING.rst
 150 .. _`generous people`: https://github.com/hynek/vim-python-pep8-indent/graphs/contributors