X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/18003a2fe16f1527a12d91a700a686ec9843f309..5fc36c048e75311b5755b667c1aca7f4d50d3562:/README.rst?ds=sidebyside diff --git a/README.rst b/README.rst index 6ffaeb6..77be58c 100644 --- a/README.rst +++ b/README.rst @@ -1,14 +1,16 @@ vim-python-pep8-indent ====================== -.. image:: https://travis-ci.org/hynek/vim-python-pep8-indent.png?branch=travis - :target: https://travis-ci.org/hynek/vim-python-pep8-indent +.. image:: https://circleci.com/gh/Vimjas/vim-python-pep8-indent.svg?style=svg + :target: https://circleci.com/gh/Vimjas/vim-python-pep8-indent +.. image:: https://codecov.io/gh/Vimjas/vim-python-pep8-indent/branch/master/graph/badge.svg + :target: https://codecov.io/gh/Vimjas/vim-python-pep8-indent -This small script modifies vim_âs indentation behavior to comply with PEP8_ and my aesthetic preferences. +This small script modifies Vim_âs indentation behavior to comply with PEP8_ and my aesthetic preferences. Most importantly:: foobar(foo, - bar) + bar) and:: @@ -21,6 +23,8 @@ and:: Installation ------------ +Install the plugin using your favorite plugin manager / method, a few examples +follow: Pathogen ^^^^^^^^ @@ -30,27 +34,90 @@ Follow the instructions on installing Pathogen_ and then: .. code-block:: shell-session $ cd ~/.vim/bundle - $ git clone https://github.com/hynek/vim-python-pep8-indent.git + $ git clone https://github.com/Vimjas/vim-python-pep8-indent.git Vundle -###### +^^^^^^ Follow the instructions on installing Vundle_ and add the appropriate plugin line into your ``.vimrc``: .. code-block:: vim - Plugin 'hynek/vim-python-pep8-indent' + Plugin 'Vimjas/vim-python-pep8-indent' NeoBundle -######### +^^^^^^^^^ Follow the instructions on installing NeoBundle_ and add the appropriate NeoBundle line into your ``.vimrc``: .. code-block:: vim - NeoBundle 'hynek/vim-python-pep8-indent' + 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 @@ -67,16 +134,18 @@ Therefore, if you want to use this version specifically, youâll have to disabl License and Authorship ---------------------- -This script is based on one from vimâs official `script repo`_ that was *not* originally written by me. -Unfortunately the indentation was off by one character in one case and hasnât been updated since 2005. +This script is based on one from Vimâs official `script repo`_ 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 it with the help of `Steve Losh`_ and am putting it out here so you donât have to patch the original yourself. +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. The original patch is still available here_. -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. +Over the time a lot more improvements have been contributed_ by `generous people`_. + +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. If anyone with a say in this objects, please let me_ know immediately. Also, if someone is in contact with one of them, I would appreciate being introduced. @@ -84,7 +153,7 @@ While my Vimscript_ 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: http://www.vim.org/ +.. _Vim: http://www.vim.org/ .. _PEP8: http://www.python.org/dev/peps/pep-0008/ .. _`script repo`: http://www.vim.org/scripts/script.php?script_id=974 .. _`Steve Losh`: http://stevelosh.com/ @@ -95,3 +164,6 @@ This mainly means that Iâll triage through bugs and pull requests but wonât .. _`Vimscript`: http://learnvimscriptthehardway.stevelosh.com/ .. _vundle: https://github.com/gmarik/Vundle.vim .. _me: https://hynek.me/ +.. _CC0: http://creativecommons.org/publicdomain/zero/1.0/ +.. _contributed: https://github.com/hynek/vim-python-pep8-indent/blob/master/CONTRIBUTING.rst +.. _`generous people`: https://github.com/hynek/vim-python-pep8-indent/graphs/contributors